sphinx (#433)

* replace rtd theme w/ pydata theme

* initial gallery setup

* Create .readthedocs.yml

* Update .gitignore

* also copy images_wiki to sphinx

* exclude .ipynb_checkpoints from tutorials file copying

Co-authored-by: Kevin Anderson <kevin.anderson@nrel.gov>
Co-authored-by: cdeline <chris.deline@nrel.gov>

.gitignore

@@ -89,6 +89,9 @@ instance/
 docs/sphinx/build/
 docs/sphinx/source/generated/
 docs/sphinx/source/savefig/
+# "docs/sphinx/source/tutorials" and "docs/sphinx/source/images_wiki" are auto-generated; see sphinx/source/conf.py
+docs/sphinx/source/tutorials/
+docs/sphinx/source/images_wiki/
 *.un~
 *.rst~
 

.readthedocs.yml

@@ -0,0 +1,9 @@
+version: 2
+
+python:
+    version: "3.7"
+    install:
+        - method: pip
+          path: .
+          extra_requirements:
+              - doc

README.md

@@ -44,7 +44,7 @@ The [Intro examples](https://bifacial-radiance.readthedocs.io/en/stable/introexa
 
 ## Contributing
 
-We need your help to make bifacial_radiance a great tool! Please see the [Contributing page](https://bifacial-radiance.readthedocs.io/en/stable/contributing.html) for more on how you can contribute. The long-term success of pvlib-python requires substantial community support.
+We need your help to make bifacial_radiance a great tool! Please see the [Contributing page](https://bifacial-radiance.readthedocs.io/en/stable/contributing.html) for more on how you can contribute. The long-term success of bifacial_radiance requires substantial community support.
 
 ## License
 
@@ -53,7 +53,7 @@ Bifacial_radiance open source code is copyrighted by the Alliance for Sustainabl
 ## Getting Support
 
 If you suspect that you may have discovered a bug or if you'd like to
-change something about pvlib, then please make an issue on our
+change something about bifacial_radiance, then please make an issue on our
 [GitHub issues page](https://github.com/NREL/bifacial_radiance/issues).
 
 bifacial_radiance questions can be asked on

docs/sphinx/source/conf.py

@@ -24,6 +24,8 @@
 
 import sys
 import os
+import shutil
+import pathlib
 
 """
 # Mock modules so RTD works
@@ -40,6 +42,10 @@ def __getattr__(cls, name):
 MOCK_MODULES = []
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 """
+# import distutils before calling pd.show_versions()
+# https://github.com/pypa/setuptools/issues/3044
+import distutils  # noqa: F401
+
 import pandas as pd
 pd.show_versions()
 
@@ -50,6 +56,14 @@ def __getattr__(cls, name):
 sys.path.insert(0, os.path.abspath('../../../'))
 
 
+# copy tutorials directory from repo root into the sphinx source directory;
+# see notes in docs/sphinx/source/examples.rst
+docs_root = pathlib.Path('./../..')
+for directory_name in ["tutorials", "images_wiki"]:
+    destination = docs_root / "sphinx" / "source" / directory_name
+    shutil.rmtree(destination, ignore_errors=True)
+    shutil.copytree(docs_root / directory_name, destination, 
+                    ignore = shutil.ignore_patterns(".ipynb_checkpoints"))
 
 
 # -- General configuration ---------------------------------------------------
@@ -70,7 +84,9 @@ def __getattr__(cls, name):
     'IPython.sphinxext.ipython_console_highlighting',
     'sphinx.ext.doctest',
     #'autoapi.extension',
-    'sphinx.ext.todo'
+    'sphinx.ext.todo',
+    'nbsphinx',
+    'sphinx_gallery.load_style',
 ]
 
 
@@ -123,16 +139,40 @@ def __getattr__(cls, name):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# on_rtd is whether we are on readthedocs.org
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+html_theme = "pydata_sphinx_theme"
+
+# https://pydata-sphinx-theme.rtfd.io/en/latest/user_guide/configuring.html
+html_theme_options = {
+    "github_url": "https://github.com/NREL/bifacial_radiance",
+    "favicons": [
+        {"rel": "icon", "sizes": "16x16", "href": "favicon-16x16.png"},
+        {"rel": "icon", "sizes": "32x32", "href": "favicon-32x32.png"},
+    ],
+    "icon_links": [
+        {
+            "name": "StackOverflow",
+            "url": "https://stackoverflow.com/questions/tagged/bifacial-radiance",
+            "icon": "fab fa-stack-overflow",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/bifacial_radiance",
+            "icon": "fab fa-python",
+        },
+    ],
+    #"use_edit_page_button": True,
+    "show_toc_level": 1,
+    "footer_items": ["copyright", "sphinx-version", "sidebar-ethical-ads"],
+    "left_sidebar_end": [],
+}
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = '../../images_wiki/bifacial_radiance.png'
 
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-else:
-    html_theme = 'default'
+# do not execute notebooks for gallery
+nbsphinx_execute = 'never'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/sphinx/source/examples.rst

@@ -0,0 +1,65 @@
+.. _examples:
+
+Examples
+========
+
+.. To select a thumbnail image, you need to edit the metadata of the cell with the
+   desired image to include a special tags value:
+        "metadata": {"tags": ["nbsphinx-thumbnail"]},
+
+.. note that linking to notebooks outside of the sphinx source directory is
+   currently not possible without using a sphinx extension like "nbsphinx-link",
+   but maintaining those link files is annoying and error-prone.  Another option
+   is to use filesystem symlinks, but those don't work on windows.
+   Instead, what we do here is to have conf.py copy the tutorials folder
+   into the source directory so that its files can be referenced directly here.
+
+
+Introductory Examples
+---------------------
+
+.. nbgallery::
+
+    tutorials/1 - Introductory Example - Fixed Tilt simple setup
+    tutorials/2 - Introductory Example - Single Axis Tracking with cumulative Sky
+
+
+Medium Level Examples
+---------------------
+
+.. nbgallery::
+
+    tutorials/3 - Medium Level Example - Single Axis Tracking - hourly
+    tutorials/4 - Medium Level Example - Debugging your Scene with Custom Objects (Fixed Tilt 2-up with Torque Tube + CLEAN Routine + CustomObject)
+    tutorials/5 - Medium Level Example - Bifacial Carports and Canopies + sampling across a module!
+    tutorials/13 - Medium Level Example - Modeling Modules with Glass
+
+
+Advanced Topcs
+--------------
+
+.. nbgallery::
+
+    tutorials/6 - Advanced topics - Understanding trackerdict structure
+    tutorials/7 - Advanced topics - Multiple SceneObjects Example
+    tutorials/8 - Advanced topics - Calculating Power Output and Electrical Mismatch
+    tutorials/9 - Advanced topics - 1 axis torque tube Shading for 1 day (Research documentation)
+    tutorials/11 - Advanced topics - AgriPV Systems
+    tutorials/12 - Advanced topics - AgriPV Clearance Height Evaluation
+    tutorials/14 - Advanced topics - Cement Pavers albedo example
+
+Other
+-----
+
+.. nbgallery::
+
+    tutorials/15 - New Functionalities Examples
+    tutorials/16 - AgriPV - 3-up and 4-up collector optimization
+    tutorials/17 - AgriPV - Jack Solar Site Modeling
+    tutorials/18 - AgriPV - Coffee Plantation with Tree Modeling
+    tutorials/19 - Example Simulation - East West Sheds
+    tutorials/20 - Example Simulation - I Beams
+    tutorials/21 - Example Simulation - Modeling Module Performance, an End to End Simulation
+    tutorials/22 - Example simulation - Mirrors and Modules
+    tutorials/Variety of Routines
+    tutorials/Webinar_Slides

docs/sphinx/source/index.rst

@@ -51,15 +51,11 @@ Contents
 .. toctree::
    :maxdepth: 3
 
-   package_overview
-   introexamples
-   whatsnew
-   installation
+   user_guide/index
+   examples
    manualapi
-   contributing
-   modelchain
+   whatsnew
    validation
-   variables_style_rules
 
 Indices and tables
 ==================

docs/sphinx/source/manualapi.rst

@@ -10,6 +10,7 @@ GUI
 
 .. autosummary::
    :toctree: generated/
+   :caption: GUI
 
    gui
 
@@ -21,6 +22,7 @@ This is a collection of classes used by bifacial_radiance for users that prefer
 
 .. autosummary::
    :toctree: generated/
+   :caption: Classes
 
    MetObj
    RadianceObj
@@ -40,6 +42,8 @@ Weather
 
 .. autosummary:: 
    :toctree: generated/
+   :caption: Weather
+
 
    RadianceObj.getEPW
    RadianceObj.readWeatherFile
@@ -50,6 +54,7 @@ Functions and methods for establishing the sources or sky domes for the simulati
 
 .. autosummary::
    :toctree: generated/
+   :caption: Sky Dome
 
    RadianceObj.genCumSky
    RadianceObj.genCumSky1axis
@@ -66,6 +71,7 @@ Functions and methods to generate modules
 
 .. autosummary::
    :toctree: generated/
+   :caption: Modules
 
    RadianceObj.makeModule
    ModuleObj.addTorquetube
@@ -83,6 +89,7 @@ Functions and methods to generate the scene.
 
 .. autosummary::
    :toctree: generated/
+   :caption: Scene
 
    RadianceObj.setGround
    RadianceObj.set1axis
@@ -95,6 +102,7 @@ Support methods for scene
 
 .. autosummary::
    :toctree: generated/
+
 
    SceneObj.showScene
    RadianceObj.makeCustomObject
@@ -108,6 +116,7 @@ Methods for irradiance calculations
 
 .. autosummary::
    :toctree: generated/
+   :caption: Irradiance Analysis
 
    AnalysisObj.moduleAnalysis
    AnalysisObj.analysis
@@ -119,6 +128,7 @@ Mismatch
 
 .. autosummary::
    :toctree: generated/
+   :caption: Mismatch Analysis
 
    mismatch.analysisIrradianceandPowerMismatch
 
@@ -130,6 +140,7 @@ Input / Output
 
 .. autosummary::
    :toctree: generated/
+   :caption: Input / Output
 
    load
    load.loadRadianceObj
@@ -144,10 +155,11 @@ Input / Output
 Visualization
 -------------
 
-Functions for visualizing iirradiance results
+Functions for visualizing irradiance results
 
 .. autosummary::
    :toctree: generated/
+   :caption: Visualization
 
    AnalysisObj.makeFalseColor
    AnalysisObj.makeImage
@@ -158,6 +170,7 @@ Others
 
 .. autosummary::
    :toctree: generated/
+   :caption: Other
 
    RadianceObj.getfilelist
    RadianceObj.getSingleTimestampTrackerAngle
@@ -168,6 +181,7 @@ ModelChain
 
 .. autosummary::
    :toctree: generated/
+   :caption: ModelChain
 
    load.readconfigurationinputfile
    modelchain.runModelChain
@@ -178,6 +192,7 @@ Spectral Analysis
 
 .. autosummary::
    :toctree: generated/
+   :caption: Spectral Analysis
 
    spectral_utils
    spectral_utils.generate_spectra

docs/sphinx/source/user_guide/index.rst

@@ -0,0 +1,14 @@
+==========
+User Guide
+==========
+
+
+.. toctree::
+   :maxdepth: 2
+
+   package_overview
+   installation
+   introexamples
+   modelchain
+   contributing
+   variables_style_rules

docs/sphinx/source/package_overview.rst → docs/sphinx/source/user_guide/package_overview.rst

@@ -7,7 +7,7 @@ The following section describes some of the functionalities of bifacial_radiance
 
 bifacial_radiance is a python wrapper for calling and using Radiance, with specific functions to generate geometry (text files) related to bifacial photovoltaic systems
 
-.. image:: ../../images_wiki/Webinar/wrapper.png
+.. image:: ../../../images_wiki/Webinar/wrapper.png
   :width: 600
 
 A full example might look like:
@@ -38,7 +38,7 @@ What this example is showing are the main/minimum instructions or steps needed t
 6. Analysis Obj - calculates the coordinates that will be sampled for irradiance. You can specify any module and row desired or custom coordinates.
 7. Analysis - runs the Radiance rtrace command and saves the measured irradiance values for the surface specified in the results folder.
 
-.. image:: ../../images_wiki/Webinar/mainsteps.png
+.. image:: ../../../images_wiki/Webinar/mainsteps.png
   :width: 600
 
 Each of this steps has more options than described here, so we really recommend looking at the  `Webinar tutorial <https://www.youtube.com/watch?v=1X9L-R-RVGA>`_ And our `Jupyter Notebook tutorials <http://github.com/NREL/bifacial_radiance/tree/master/docs/tutorials/>`_, as well as the :ref:`manualapi` as each function has description of input parameters.

setup.py

@@ -112,12 +112,19 @@
 
 
     extras_require={
-        'all': [
+        'doc': [
             'ipython',
-            'jupyter',
             'sphinx >= 1.8.0',
             'sphinx-autoapi>=1.1.0',
-            'sphinx-rtd-theme>=0.4.3',
+            'pydata-sphinx-theme==0.8.1',
+            'nbsphinx==0.8.8',
+            # sphinx-gallery is used indirectly for nbsphinx thumbnail galleries; see:
+            # https://nbsphinx.readthedocs.io/en/0.6.0/subdir/gallery.html#Creating-Thumbnail-Galleries
+            'sphinx-gallery==0.8.1',
+        ],
+        'all': [
+            'ipython',
+            'jupyter',
             'pytest',
             'pytest-cov',
             'pySMARTS',