diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index b3c301092a..2b6b3efc23 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -247,12 +247,42 @@ Parameters that specify a specific type require that specific input type. Read the Docs will automatically build the documentation for each pull request. Please confirm the documentation renders correctly by following -the ``continuous-documentation/read-the-docs`` link within the checks +the ``docs/readthedocs.org:pvlib-python`` link within the checks status box at the bottom of the pull request. -To build the docs locally, install the ``doc`` dependencies specified in the -`setup.py `_ -file. See :ref:`installation` instructions for more information. +Building the documentation +-------------------------- + +Building the documentation locally is useful for testing out changes to the +documentation's source code without having to repeatedly update a PR and have +Read the Docs build it for you. Building the docs locally requires installing +pvlib python as an editable library (see :ref:`installation` for instructions). +First, install the ``doc`` dependencies specified in the +``EXTRAS_REQUIRE`` section of +`setup.py `_. +An easy way to do this is with:: + + pip install pvlib[doc] + +Note: Anaconda users may have trouble using the above command to update an +older version of docutils. If that happens, you can update it with ``conda`` +(e.g. ``conda install docutils=0.15.2``) and run the above command again. + +Once the ``doc`` dependencies are installed, navigate to ``/docs/sphinx`` and +execute:: + + make html + +Be sure to skim through the output of this command because Sphinx might emit +helpful warnings about problems with the documentation source code. +If the build succeeds, it will make a new directory ``docs/sphinx/build`` +with the documentation's homepage located at ``build/html/index.html``. +This file can be opened with a web browser to view the local version +like any other website. Other output formats are available; run ``make help`` +for more information. + +Note that Windows users need not have the ``make`` utility installed as pvlib +includes a ``make.bat`` batch file that emulates its interface. Example Gallery --------------- diff --git a/docs/sphinx/source/whatsnew/v0.8.0.rst b/docs/sphinx/source/whatsnew/v0.8.0.rst index f901add383..1b8b28aee2 100644 --- a/docs/sphinx/source/whatsnew/v0.8.0.rst +++ b/docs/sphinx/source/whatsnew/v0.8.0.rst @@ -44,6 +44,7 @@ Documentation * Clarify units for heat loss factors in :py:func:`pvlib.temperature.pvsyst_cell` and :py:func:`pvlib.temperature.faiman`. (:pull:`960`) +* Add instructions to build the documentation. (:pull:`982`) * Corrected key names for :py:func:`pvlib.inverter.sandia`. (:issue:`976`, :pull:`886`) * Add a transposition gain example to the gallery. (:pull:`979`) diff --git a/readthedocs.yml b/readthedocs.yml index df675e2a79..fb2d1374bb 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -1,6 +1,7 @@ python: version: 3 - use_system_site_packages: true + # only use the packages specified in setup.py + use_system_site_packages: false pip_install: true extra_requirements: - - all \ No newline at end of file + - doc \ No newline at end of file diff --git a/setup.py b/setup.py index 6e5f6ad372..2ec97ce506 100755 --- a/setup.py +++ b/setup.py @@ -47,7 +47,8 @@ 'optional': ['ephem', 'cython', 'netcdf4', 'nrel-pysam', 'numba', 'pvfactors', 'scipy', 'siphon', 'tables', 'cftime >= 1.1.1'], 'doc': ['ipython', 'matplotlib', 'sphinx == 1.8.5', 'sphinx_rtd_theme', - 'sphinx-gallery', 'docutils == 0.15.2'], + 'sphinx-gallery', 'docutils == 0.15.2', 'pillow', 'scipy', + 'netcdf4', 'siphon', 'tables'], 'test': TESTS_REQUIRE } EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), [])))