Bump docs infraestructure (#2112)

* Initial version bump

* Pin latests, okay

* Update extlinks

See sphinx#11094

* add entries to html_context, from pydata sphinx theme

* Update edit-this-page.html

* Update edit-this-page.html

* Update conf.py

* Update conf.py

* Footer warning

* `"left_sidebar_end"` -> `"primary_sidebar_end"`

* Add favicons

* Add favicons dependency

* GH desktop is a bit broken

* linter

* Edit link (I?)

* `"use_edit_page_button": True,` else I can't test it xd

* Add `edit-this-page.html` again

* `html_show_sourcelink = False`

* Update conf.py

* this was unnecessary

* Update edit-this-page.html

https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#custom-link-text

* Revert "Update edit-this-page.html"

This reverts commit 4175be5.

* Update conf.py

* Suppress warnings

See numpy#25504

* Revert back to original

* Did I already try this?

* Using the docs

* Fix the edit -> view on github

* linter

* No way linter

* Fix references formatting

Co-Authored-By: Kevin Anderson <[email protected]>

* Remove prev/next links

Co-Authored-By: Kevin Anderson <[email protected]>
Co-Authored-By: Adam R. Jensen <[email protected]>
Co-Authored-By: RDaxini <[email protected]>
Co-Authored-By: Cliff Hansen <[email protected]>

* Delay updating docs build env in the future

Co-Authored-By: Adam R. Jensen <[email protected]>

* Copyright

Co-Authored-By: Adam R. Jensen <[email protected]>

* Fix empty sidebar not collapsing (I hope)

Co-Authored-By: Adam R. Jensen <[email protected]>

* Stylize navigation and footer per Adam comment

Co-Authored-By: Adam R. Jensen <[email protected]>

* linter on diff F

* Update docs/sphinx/source/conf.py

Co-authored-by: Adam R. Jensen <[email protected]>

---------

Co-authored-by: Kevin Anderson <[email protected]>
Co-authored-by: Adam R. Jensen <[email protected]>
Co-authored-by: RDaxini <[email protected]>
Co-authored-by: Cliff Hansen <[email protected]>

Author: 5 people

docs/sphinx/source/_static/reference_format.css

@@ -1,13 +1,5 @@
 /* no reference superscript */
 .footnote-reference {
-    font-size: 100% !important;  /* default is 90% */
-    top: 0.0em !important;  /* default is -0.4em */
-}
-
-/* reference number in brackets */
-.footnote-reference::before {
-  content: '[';
-}
-.footnote-reference::after {
-  content: ']';
+  font-size: 100% !important;
+  vertical-align: baseline !important;
 }

docs/sphinx/source/_templates/edit-this-page.html

@@ -1,19 +1,16 @@
 {#
 
 Modify the "Edit on Github" links to handle auto-generated pages in the
-example gallery and the API reference listings.  The GH links that sphinx
+example gallery and the API reference listings. The GH links that sphinx
 generates by default make the assumption that an HTML file comes from an RST
 file with the same filepath, which isn't the case for autogenerated files. The
 logic to generate the correct URL is in conf.py, but we still have to modify
 the template here to change the "Edit this page" text to "View on GitHub".
 
 #}
 
-{% if sourcename is defined and theme_use_edit_page_button==true and page_source_suffix %}
-{% set src = sourcename.split('.') %}
-<div class="tocsection editthispage">
-    <a href="{{ get_edit_url() }}">
-        <i class="fab fa-github-square"></i> {{ _("View on GitHub") }}
-    </a>
-</div>
-{% endif %}
+{% extends "!components/edit-this-page.html" %}
+
+{% block edit_this_page_text %}
+  View on GitHub
+{% endblock %}

docs/sphinx/source/conf.py

@@ -24,6 +24,7 @@
 # https://github.com/pypa/setuptools/issues/3044
 import distutils  # noqa: F401
 import pandas as pd
+
 pd.show_versions()
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -54,6 +55,7 @@
     'IPython.sphinxext.ipython_console_highlighting',
     'sphinx_gallery.gen_gallery',
     'sphinx_toggleprompt',
+    'sphinx_favicon',
 ]
 
 mathjax3_config = {'chtml': {'displayAlign': 'left',
@@ -83,7 +85,7 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 
-import pvlib
+import pvlib  # noqa: E402
 
 # The short X.Y version.
 version = '%s' % (pvlib.__version__)
@@ -142,10 +144,6 @@
 # https://pydata-sphinx-theme.rtfd.io/en/latest/user_guide/configuring.html
 html_theme_options = {
     "github_url": "https://github.com/pvlib/pvlib-python",
-    "favicons": [
-        {"rel": "icon", "sizes": "16x16", "href": "favicon-16x16.png"},
-        {"rel": "icon", "sizes": "32x32", "href": "favicon-32x32.png"},
-    ],
     "icon_links": [
         {
             "name": "StackOverflow",
@@ -165,12 +163,23 @@
     ],
     "use_edit_page_button": True,
     "show_toc_level": 1,
-    "footer_items": ["copyright", "sphinx-version", "sidebar-ethical-ads"],
-    "left_sidebar_end": [],
-}
+    # "footer_start": [],  # "copyright", "sphinx-version"
+    # "footer_center": [],
+    "footer_end": [],
+    # "primary_sidebar_end": [],
+    # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#hide-the-previous-and-next-buttons
+    "show_prev_next": False,  # disable next/previous links
+}  # noqa: E501
+
+# Add favicons from extension sphinx_favicon
+favicons = [
+    {"rel": "icon", "sizes": "16x16", "href": "favicon-16x16.png"},
+    {"rel": "icon", "sizes": "32x32", "href": "favicon-32x32.png"},
+]
+
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -196,40 +205,42 @@
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
-#html_extra_path = []
+# html_extra_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+# html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-#html_use_smartypants = True
+# html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+# html_sidebars = {
+#     "**": ["sidebar-nav-bs"]
+# }
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+# html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+# html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+# html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
-#html_split_index = False
+# html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+# html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-html_show_copyright = False
+# html_show_copyright = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -297,12 +308,15 @@ def setup(app):
 
 # extlinks alias
 extlinks = {
-    'issue': ('https://github.com/pvlib/pvlib-python/issues/%s', 'GH'),
-    'pull': ('https://github.com/pvlib/pvlib-python/pull/%s', 'GH'),
-    'wiki': ('https://github.com/pvlib/pvlib-python/wiki/%s', 'wiki '),
-    'doi': ('http://dx.doi.org/%s', 'DOI: '),
-    'ghuser': ('https://github.com/%s', '@'),
-    'discuss': ('https://github.com/pvlib/pvlib-python/discussions/%s', 'GH'),
+    "issue": ("https://github.com/pvlib/pvlib-python/issues/%s", "GH%s"),
+    "pull": ("https://github.com/pvlib/pvlib-python/pull/%s", "GH%s"),
+    "wiki": ("https://github.com/pvlib/pvlib-python/wiki/%s", "wiki %s"),
+    "doi": ("http://dx.doi.org/%s", "DOI: %s"),
+    "ghuser": ("https://github.com/%s", "@%s"),
+    "discuss": (
+        "https://github.com/pvlib/pvlib-python/discussions/%s",
+        "GH%s",
+    ),
 }
 
 # -- Options for manual page output ---------------------------------------

pyproject.toml

@@ -56,13 +56,15 @@ optional = [
 ]
 doc = [
     'ipython',
+    'pickleshare',  # required by ipython
     'matplotlib',
-    'sphinx == 4.5.0',
-    'pydata-sphinx-theme == 0.8.1',
+    'sphinx == 7.3.7',
+    'pydata-sphinx-theme == 0.15.4',
     'sphinx-gallery',
-    'docutils == 0.15.2',
+    'docutils == 0.21',
     'pillow',
-    'sphinx-toggleprompt >= 0.0.5',
+    'sphinx-toggleprompt == 0.5.2',
+    'sphinx-favicon',
     'solarfactors',
 ]
 test = [

readthedocs.yml

@@ -6,9 +6,9 @@
 version: 2
 
 build:
-   os: ubuntu-20.04
+   os: ubuntu-lts-latest
    tools:
-     python: "3.8"
+     python: "3.11"
    jobs:
      # fetch the full history so that setuptools_scm can determine the
      # correct version string for long PRs with many commits