From 4227ff842946b836f086f08ab8e0b213c32aa146 Mon Sep 17 00:00:00 2001 From: kanderso-nrel Date: Sat, 22 Feb 2020 11:21:32 -0700 Subject: [PATCH 1/4] add section about gallery examples to contributing guide --- docs/sphinx/source/contributing.rst | 33 +++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/sphinx/source/contributing.rst b/docs/sphinx/source/contributing.rst index f7932de97f..408296508a 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -254,6 +254,39 @@ To build the docs locally, install the ``doc`` dependencies specified in the `setup.py `_ file. See :ref:`installation` instructions for more information. +Example Gallery +--------------- + +The example gallery uses `sphinx-gallery `_ +and is generated from script files in the +`docs/examples `_ +directory. sphinx-gallery will execute example files that start with +``plot_`` and capture the output. + +Here is a starter template for new examples: + +.. code-block:: python + + """ + Page Title + ========== + + A sentence describing the example. + """ + + # %% + # Explanatory text about the example, what it does, + # why it does it, etc. + + import pvlib + import matplotlib.pyplot as plt + + plt.scatter([1, 2, 3], [4, 5, 6]) + plt.show() + +For more details, see the sphinx-gallery +`docs `_. + .. _testing: Testing From 01b4e399aa9e74ca651c2fd9259d0b829dd680de Mon Sep 17 00:00:00 2001 From: kanderso-nrel Date: Sat, 22 Feb 2020 11:23:56 -0700 Subject: [PATCH 2/4] whatsnew --- docs/sphinx/source/whatsnew/v0.7.2.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/source/whatsnew/v0.7.2.rst b/docs/sphinx/source/whatsnew/v0.7.2.rst index f788c6bf0d..66d08226ad 100644 --- a/docs/sphinx/source/whatsnew/v0.7.2.rst +++ b/docs/sphinx/source/whatsnew/v0.7.2.rst @@ -40,6 +40,7 @@ Documentation ~~~~~~~~~~~~~ * Add NumFOCUS affiliation to Sphinx documentation :pull:`862` * Add example of IV curve generation :pull:`872` +* Add section about gallery examples to Contributing guide Requirements ~~~~~~~~~~~~ From f34fb2222cd6248839a6389e12c413daec2296b4 Mon Sep 17 00:00:00 2001 From: kanderso-nrel Date: Sat, 22 Feb 2020 11:32:03 -0700 Subject: [PATCH 3/4] whatsnew cleanup --- docs/sphinx/source/whatsnew/v0.7.2.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/whatsnew/v0.7.2.rst b/docs/sphinx/source/whatsnew/v0.7.2.rst index 66d08226ad..a63440c9bf 100644 --- a/docs/sphinx/source/whatsnew/v0.7.2.rst +++ b/docs/sphinx/source/whatsnew/v0.7.2.rst @@ -38,9 +38,9 @@ Bug fixes Documentation ~~~~~~~~~~~~~ -* Add NumFOCUS affiliation to Sphinx documentation :pull:`862` -* Add example of IV curve generation :pull:`872` -* Add section about gallery examples to Contributing guide +* Add NumFOCUS affiliation to Sphinx documentation (:pull:`862`) +* Add example of IV curve generation (:pull:`872`) +* Add section about gallery examples to Contributing guide (:pull:`905`) Requirements ~~~~~~~~~~~~ From 975e6bbf10c9855f19c78a9a5520dd2778905f0c Mon Sep 17 00:00:00 2001 From: kanderso-nrel Date: Sun, 23 Feb 2020 21:16:06 -0700 Subject: [PATCH 4/4] add review suggestion --- 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 1e0fabd3c7..5a629730af 100644 --- a/docs/sphinx/source/contributing.rst +++ b/docs/sphinx/source/contributing.rst @@ -275,8 +275,9 @@ Here is a starter template for new examples: """ # %% - # Explanatory text about the example, what it does, - # why it does it, etc. + # Explanatory text about the example, what it does, why it does it, etc. + # Text in the comment block before the first line of code `import pvlib` + # will be printed to the example's webpage. import pvlib import matplotlib.pyplot as plt