From 10cd7005c85f3356b8d55b1887417a3fb12b4860 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 12 Jun 2020 20:03:23 -0600 Subject: [PATCH 1/8] Update contributing.rst --- docs/sphinx/source/contributing.rst | 31 ++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index b3c301092a..d57869cea5 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -247,12 +247,37 @@ 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 +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 `setup.py `_ -file. See :ref:`installation` instructions for more information. +file. An easy way to do this is with:: + + pip install pvlib[doc] + +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 --------------- From f0bce21eb450b209f5e76ef185795166a232dc65 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 12 Jun 2020 20:05:40 -0600 Subject: [PATCH 2/8] whatsnew --- docs/sphinx/source/whatsnew/v0.8.0.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/source/whatsnew/v0.8.0.rst b/docs/sphinx/source/whatsnew/v0.8.0.rst index d4f7bf3956..b4fd3f1c80 100644 --- a/docs/sphinx/source/whatsnew/v0.8.0.rst +++ b/docs/sphinx/source/whatsnew/v0.8.0.rst @@ -26,6 +26,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`) Requirements ~~~~~~~~~~~~ From e6cd308b4f9516ea4613b66e2cba4e54fa1ba566 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 6 Jul 2020 11:09:25 -0600 Subject: [PATCH 3/8] review improvements --- docs/sphinx/source/contributing.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index d57869cea5..2216f9d519 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -257,9 +257,10 @@ 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 -`setup.py `_ -file. An easy way to do this is with:: +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] From 3772a8c283672b67e0bc8aef360106fa2e3bce75 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 6 Jul 2020 21:00:01 -0600 Subject: [PATCH 4/8] install optional as well as doc --- docs/sphinx/source/contributing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 2216f9d519..5232f13d9c 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -257,11 +257,12 @@ 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 +First, install the ``optional`` and ``doc`` dependencies specified in the +``EXTRAS_REQUIRE`` section of `setup.py `_. An easy way to do this is with:: + pip install pvlib[optional] pip install pvlib[doc] Once the ``doc`` dependencies are installed, navigate to ``/docs/sphinx`` and From 12f6786903af647a52e2cdab33edf94affe83e36 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Mon, 6 Jul 2020 21:00:41 -0600 Subject: [PATCH 5/8] add pillow to doc requirements --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 6e5f6ad372..09e6a14ef8 100755 --- a/setup.py +++ b/setup.py @@ -47,7 +47,7 @@ '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'], 'test': TESTS_REQUIRE } EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), []))) From 208aafa0893a316760a8c55e1cf236f66c73c9a5 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 9 Jul 2020 18:06:39 -0600 Subject: [PATCH 6/8] update doc requirements list --- docs/sphinx/source/contributing.rst | 7 +++++-- setup.py | 3 ++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index 5232f13d9c..2b6b3efc23 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -257,14 +257,17 @@ 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 ``optional`` and ``doc`` dependencies specified in the +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[optional] 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:: diff --git a/setup.py b/setup.py index 09e6a14ef8..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', 'pillow'], + 'sphinx-gallery', 'docutils == 0.15.2', 'pillow', 'scipy', + 'netcdf4', 'siphon', 'tables'], 'test': TESTS_REQUIRE } EXTRAS_REQUIRE['all'] = sorted(set(sum(EXTRAS_REQUIRE.values(), []))) From 35d709c70fd924077d8352530b0f6c72fd006ea6 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 9 Jul 2020 18:08:19 -0600 Subject: [PATCH 7/8] only install [doc] instead of [all] for RTD --- readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readthedocs.yml b/readthedocs.yml index df675e2a79..fd1cc5a518 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -3,4 +3,4 @@ python: use_system_site_packages: true pip_install: true extra_requirements: - - all \ No newline at end of file + - doc \ No newline at end of file From e170c9f658d147c81570e4421e99599d84178e42 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 9 Jul 2020 19:31:24 -0600 Subject: [PATCH 8/8] turn off system packages for RTD --- readthedocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/readthedocs.yml b/readthedocs.yml index fd1cc5a518..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: - doc \ No newline at end of file