DOC: Migrate to pydata-sphinx-theme

.github/workflows/tests.yml

@@ -27,7 +27,7 @@ jobs:
       # Ensure that a wheel builder finishes even if another fails
       fail-fast: false
       matrix:
-        python-version: [3.9, '3.10', '3.11', '3.12']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         MINIMUM_REQUIREMENTS: [0]
         USE_SCIPY: [0]
         USE_SDIST: [0]
@@ -36,15 +36,15 @@ jobs:
         OPTIONS_NAME: ["default"]
         include:
           - platform_id: manylinux_x86_64
-            python-version: 3.9
+            python-version: '3.9'
             MINIMUM_REQUIREMENTS: 1
             OPTIONS_NAME: "minimum-req"
           - platform_id: manylinux_x86_64
-            python-version: 3.9
+            python-version: '3.9'
             USE_SCIPY: 1
             OPTIONS_NAME: "with-scipy"
           - platform_id: manylinux_x86_64
-            python-version: 3.9
+            python-version: '3.9'
             USE_SDIST: 1
             OPTIONS_NAME: "install-from-sdist"
           - platform_id: manylinux_x86_64
@@ -114,7 +114,11 @@ jobs:
                 pytest --pyargs pywt
                 python ../pywt/tests/test_doc.py
             elif [ "${REFGUIDE_CHECK}" == "1" ]; then
+                # Run doctests and check if the refguide contains entries from __all__
                 python util/refguide_check.py --doctests
+                # Run Sphinx HTML docs builder, converting warnings to errors
+                pip install -r util/readthedocs/requirements.txt
+                sphinx-build -b html -W --keep-going -d _build/doctrees . doc/source doc/build
             else
                 pytest --pyargs pywt
             fi
@@ -136,7 +140,7 @@ jobs:
       # Ensure that a wheel builder finishes even if another fails
       fail-fast: false
       matrix:
-        python-version: [3.9, '3.12']
+        python-version: ['3.9', '3.12']
         MINIMUM_REQUIREMENTS: [0]
         USE_SCIPY: [0]
         USE_SDIST: [0]

doc/release/0.5.0-notes.rst

@@ -41,7 +41,7 @@ New features
 ============
 
 1D Continuous Wavelet Transforms
--------------------------------
+--------------------------------
 A wide range of continuous wavelets are now available.  These include the
 following:
 

doc/source/conf.py

@@ -11,13 +11,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import re
 import datetime
-import jinja2.filters
+import importlib.metadata
 
 import numpy as np
 
 # FIXME: doctests need the str/repr formatting used in Numpy < 1.14.
+# Should this be removed or updated?
 try:
     np.set_printoptions(legacy='1.13')
 except TypeError:
@@ -33,11 +33,20 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.todo',
-              'sphinx.ext.extlinks', 'sphinx.ext.mathjax',
-              'sphinx.ext.autosummary', 'numpydoc',
-              'sphinx.ext.intersphinx',
-              'matplotlib.sphinxext.plot_directive']
+extensions = [
+    'matplotlib.sphinxext.plot_directive',
+    'numpydoc',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary', 
+    'sphinx.ext.doctest',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.todo',
+    'sphinx_copybutton',
+    'sphinx_togglebutton',
+
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -46,7 +55,7 @@
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8'
+source_encoding = 'utf-8'
 
 # The master toctree document.
 master_doc = 'index'
@@ -61,11 +70,11 @@
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
-import pywt
-version = re.sub(r'\.dev0+.*$', r'.dev', pywt.__version__)
-release = pywt.__version__
 
-print("PyWavelets (VERSION %s)" % (version,))
+version = importlib.metadata.version('pywavelets')
+release = version
+
+print(f"PyWavelets (VERSION {version})")
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -108,26 +117,73 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'nature'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
+# further. For a list of options available for each theme, see the documentation
+# at https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html
+html_theme_options = {
+"navbar_start": ["navbar-logo"],
+"navbar_center": ["navbar-nav"],
+"navbar_end": ["navbar-icon-links", "theme-switcher"],
+"navbar_persistent": ["search-button"],
+"primary_sidebar_end": ["indices.html", "sidebar-ethical-ads.html"],
+"show_nav_level": 2,
+"navigation_depth": 2,
+"show_toc_level": 2,
+"use_edit_page_button": True,
+"github_url": "https://github.com/PyWavelets/pywt",
+"secondary_sidebar_items": {
+    "**": ["page-toc", "sourcelink", "edit-this-page"],
+    "index": ["page-toc"],
+},
+"show_prev_next": True,
+"footer_start": ["copyright", "sphinx-version"],
+"footer_end": ["theme-version"],
+"pygment_light_style": "a11y-high-contrast-light",
+"pygment_dark_style": "a11y-high-contrast-dark",
+"icon_links": [
+        {
+            "name": "Discussion group on Google Groups",
+            "url": "https://groups.google.com/group/pywavelets",
+            # Icon class (if "type": "fontawesome"), or path to local image (if "type": "local")
+            "icon": "fa-regular fa-comments",
+            # The type of image to be used (see below for details)
+            "type": "fontawesome",
+        },
+        {
+            "name": "Explore PyWavelets",
+            "url": "http://wavelets.pybytes.com/",
+            "icon": "fa-solid fa-wave-square",
+            "type": "fontawesome",
+        }
+   ],
+"icon_links_label": "Quick Links",
+}
+
+# Contexts to extract GitHub links for edit buttons and theme switcher
+html_context = {
+    "github_url": "https://github.com", # or your GitHub Enterprise site
+    "github_user": "PyWavelets",
+    "github_repo": "pywt",
+    "github_version": "master",
+    "doc_path": "doc/source",
+    "default_mode": "light",
+}
 
 # 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".
 html_title = 'PyWavelets Documentation'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+# html_short_title = None
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+# html_logo = None
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -145,26 +201,26 @@
 
 # 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 = {
-   '**': ['localtoc.html', "relations.html", 'quicklinks.html', 'searchbox.html', 'editdocument.html'],
+    "**": ["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_use_modindex = True
+# html_use_modindex = 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 = False
@@ -175,7 +231,7 @@
 html_use_opensearch = 'http://pywavelets.readthedocs.org'
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
+# html_file_suffix = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'PyWaveletsdoc'
@@ -184,10 +240,10 @@
 # -- Options for LaTeX output --------------------------------------------------
 
 # The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
+# latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+# latex_font_size = '10pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
@@ -198,20 +254,20 @@
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+# latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-#latex_use_parts = False
+# latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
+# latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
 
 # If false, no module index is generated.
-#latex_use_modindex = True
+# latex_use_modindex = True
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -230,4 +286,6 @@
 
 # Intersphinx to get Numpy and other targets
 intersphinx_mapping = {
-    'numpy': ('https://numpy.org/devdocs', None)}
+    'numpy': ('https://numpy.org/devdocs', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
+    }