Add instructions for building the docs (#982)

* Update contributing.rst

* whatsnew

* review improvements

* install optional as well as doc

* add pillow to doc requirements

* update doc requirements list

* only install [doc] instead of [all] for RTD

* turn off system packages for RTD

Author: kandersolar

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 <https://github.com/pvlib/pvlib-python/blob/master/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 <https://github.com/pvlib/pvlib-python/blob/master/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
 ---------------

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`)

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
+        - doc

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(), [])))