Miscellaneous sphinx fixes (#1365)

* clean up internal links

* fix the pvlib-maintainer tagging instructions

* clean up surfrad.py

* update ad location for new theme version

* pin theme version

* update broken wfcsv.pdf links

* switch to just tagging pvlib, not the untaggable pvlib-maintainer team

* fix silly md/rst confusion

Author: kandersolar

docs/sphinx/source/conf.py

@@ -159,6 +159,7 @@
     "use_edit_page_button": True,
     "show_toc_level": 1,
     "footer_items": ["copyright", "sphinx-version", "sidebar-ethical-ads"],
+    "left_sidebar_end": [],
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -199,9 +200,7 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-    "**": ["search-field", "sidebar-nav-bs"]  # "sidebar-ethical-ads"
-}
+# html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/sphinx/source/contributing.rst

@@ -150,13 +150,14 @@ a timely manner is to:
 
 #. Start by creating an issue. The issue should be well-defined and
    actionable.
-#. Ask the maintainers to tag the issue with the appropriate milestone.
+#. Ask the `maintainers <https://github.com/orgs/pvlib/people>`_ to tag
+   the issue with the appropriate milestone.
 #. Make a limited-scope pull request. It can be a lot of work to check all of
    the boxes in `pull request guidelines
    <https://github.com/pvlib/pvlib-python/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_,
    especially for pull requests with a lot of new primary code.
    See :ref:`pull-request-scope`.
-#. Tag pvlib community members or ``@pvlib/maintainer`` when the pull
+#. Tag pvlib community members or ``@pvlib`` when the pull
    request is ready for review. (see :ref:`pull-request-reviews`)
 
 
@@ -166,7 +167,7 @@ Pull request reviews
 --------------------
 
 The pvlib community and maintainers will review your pull request in a
-timely fashion. Please "ping" ``@pvlib/maintainer`` if it seems that
+timely fashion. Please "ping" ``@pvlib`` if it seems that
 your pull request has been forgotten at any point in the pull request
 process.
 

docs/tutorials/irradiance.ipynb

@@ -367,7 +367,7 @@
    "source": [
     "See the online documentation for clear sky modeling examples.\n",
     "\n",
-    "http://pvlib-python.readthedocs.io/en/latest/clearsky.html\n",
+    "http://pvlib-python.readthedocs.io/en/stable/user_guide/clearsky.html\n",
     "\n",
     "Here we only generate data for the functions below."
    ]

pvlib/iotools/midc.py

@@ -187,8 +187,8 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
              {'Global Horizontal [W/m^2]': 'ghi'}
 
     See the MIDC_VARIABLE_MAP for collection of mappings by site.
-    For a full list of pvlib variable names see the `Variable Style Rules
-    <https://pvlib-python.readthedocs.io/en/latest/variables_style_rules.html>`_.
+    For a full list of pvlib variable names see the
+    :ref:`variables_style_rules`.
 
     Be sure to check the units for the variables you will use on the
     `MIDC site <https://midcdmz.nrel.gov/>`_.

pvlib/iotools/psm3.py

@@ -262,7 +262,7 @@ def parse_psm3(fbuf):
     .. [1] `NREL National Solar Radiation Database (NSRDB)
        <https://nsrdb.nrel.gov/>`_
     .. [2] `Standard Time Series Data File Format
-       <https://rredc.nrel.gov/solar/old_data/nsrdb/2005-2012/wfcsv.pdf>`_
+       <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
     """
     # The first 2 lines of the response are headers with metadata
     metadata_fields = fbuf.readline().split(',')
@@ -331,7 +331,7 @@ def read_psm3(filename):
     .. [1] `NREL National Solar Radiation Database (NSRDB)
        <https://nsrdb.nrel.gov/>`_
     .. [2] `Standard Time Series Data File Format
-       <https://rredc.nrel.gov/solar/old_data/nsrdb/2005-2012/wfcsv.pdf>`_
+       <https://web.archive.org/web/20170207203107/https://sam.nrel.gov/sites/default/files/content/documents/pdf/wfcsv.pdf>`_
     """
     with open(str(filename), 'r') as fbuf:
         content = parse_psm3(fbuf)

pvlib/iotools/surfrad.py

@@ -47,7 +47,7 @@ def read_surfrad(filename, map_variables=True):
         Filepath or url.
     map_variables: bool
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable SURFRAD_COLUMNS.
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------
@@ -113,7 +113,7 @@ def read_surfrad(filename, map_variables=True):
     =======================  ======  ==========================================
 
     See README files located in the station directories in the SURFRAD
-    data archives[2]_ for details on SURFRAD daily data files.
+    data archives [2]_ for details on SURFRAD daily data files.
 
     References
     ----------

pvlib/modelchain.py

@@ -382,8 +382,7 @@ class ModelChain:
     appropriate model parameters. For example, if ``dc_model='pvwatts'``,
     then each ``Array.module_parameters`` must contain ``'pdc0'``.
 
-    See https://pvlib-python.readthedocs.io/en/stable/modelchain.html
-    for examples.
+    See :ref:`modelchaindoc` for examples.
 
     Parameters
     ----------

setup.py

@@ -57,8 +57,8 @@
                  'pvfactors', 'siphon', 'statsmodels',
                  'cftime >= 1.1.1'],
     'doc': ['ipython', 'matplotlib', 'sphinx == 3.1.2',
-            'pydata-sphinx-theme', 'sphinx-gallery', 'docutils == 0.15.2',
-            'pillow', 'netcdf4', 'siphon',
+            'pydata-sphinx-theme == 0.8.0', 'sphinx-gallery',
+            'docutils == 0.15.2', 'pillow', 'netcdf4', 'siphon',
             'sphinx-toggleprompt >= 0.0.5'],
     'test': TESTS_REQUIRE
 }