[MRG] Change Sphinx theme (and fix minor typos)

doc/Makefile

@@ -25,7 +25,7 @@ help:
 	@echo "  html-noplot to make standalone HTML files, without plotting anything"
 	@echo "  html       to make standalone HTML files"
 	@echo "  html_dev-pattern to make standalone HTML files for one example dir (dev version)"
-	@ech "   view	    to view the documentation in a browser"
+	@echo "  view	    to view the documentation in a browser"
 	@echo "  linkcheck        to check all external links for integrity"
 
 .PHONY: clean
@@ -37,7 +37,7 @@ clean:
 	rm -rf modules/*
 
 html-noplot:
-	$(SPHINXBUILD) -D plot_gallery=0 -D -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

doc/_static/versions.json

@@ -0,0 +1,32 @@
+[
+    {
+        "name": "Development",
+        "version": "dev",
+        "url": "https://jonescompneurolab.github.io/hnn-core/dev/index.html"
+    },
+    {
+        "name": "Stable",
+        "version": "stable",
+        "url": "https://jonescompneurolab.github.io/hnn-core/stable/index.html"
+    },
+    {
+        "name": "v0.4",
+        "version": "0.4",
+        "url": "https://jonescompneurolab.github.io/hnn-core/v0.4/index.html"
+    },
+    {
+        "name": "v0.3",
+        "version": "0.3",
+        "url": "https://jonescompneurolab.github.io/hnn-core/v0.3/index.html"
+    },
+    {
+        "name": "v0.2",
+        "version": "0.2",
+        "url": "https://jonescompneurolab.github.io/hnn-core/v0.2/index.html"
+    },
+    {
+        "name": "v0.1",
+        "version": "0.1",
+        "url": "https://jonescompneurolab.github.io/hnn-core/v0.1/index.html"
+    }
+]

doc/conf.py

@@ -14,12 +14,8 @@
 #
 import os
 import sys
-# sys.path.insert(0, os.path.abspath('.'))
-import sphinx_gallery
 from sphinx_gallery.sorting import ExampleTitleSortKey, ExplicitOrder
 
-import sphinx_bootstrap_theme
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -98,48 +94,68 @@
 # This pattern also affects html_static_path and html_extra_path .
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'gui/index.rst']
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+html_theme = "pydata_sphinx_theme"
+
+# versions
+#
+# TODO GH #969 Once we're ready to merge this into `master`, we need to switch
+# this to dev's version
 #
-html_theme = 'bootstrap'
+# The actual, local version of `versions.json` that you should edit (if
+# necessary) is in `_static/versions.json`.
+json_versions_url = "https://jonescompneurolab.github.io/hnn-core/stable/_static/versions.json"
+switcher_version_match = "dev" if ".rc" in version else version
 
 # 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.
-#
+# documentation:
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html
 html_theme_options = {
-    'navbar_sidebarrel': False,
-    'navbar_links': [
-        ("Examples", "auto_examples/index"),
-        ("API", "api"),
-        ("Glossary", "glossary"),
-        ("What's new", "whats_new"),
-        ("GitHub", "https://github.com/jonescompneurolab/hnn-core", True)
+    "external_links": [
+        {
+            "url": "https://github.com/jonescompneurolab/hnn-core",
+            "name": "GitHub (Code)",
+        },
+        {
+            "url": "https://pypi.org/project/hnn-core/",
+            "name": "PyPI",
+        },
+        {
+            "url": "https://hnn.brown.edu/",
+            "name": "HNN Frontpage",
+        },
     ],
-    'bootswatch_theme': "yeti"
+    "header_links_before_dropdown": 7,
+    "navbar_align": "left",
+    "navbar_start": ["navbar-logo"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["version-switcher"],
+    "pygments_dark_style": "monokai",
+    "switcher": {
+        "json_url": json_versions_url,
+        "version_match": switcher_version_match,
+    },
 }
 
 # 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,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
-
+# so a file named "default.css" will overwrite the builtin "default.css". This
+# folder also holds versions.json.
+html_static_path = ["_static"]
+html_logo = "_static/hnn-medium.png"
+
+# The default sidebars (for documents that don't match any pattern) are defined
+# by theme itself.  Builtin themes are using these templates by default:
+# ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``. Not that the following removes the "primary" sidebar (on
+# the left), but not the "secondary" # sidebar (on the right), for the PyData
+# theme. From
+# https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/layout.html#remove-the-primary-sidebar-from-pages
+html_sidebars = {
+    "**": []
+}
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

setup.py

@@ -79,12 +79,10 @@ def run(self):
         'opt': ['scikit-learn'],
         'parallel': ['joblib', 'psutil'],
         'test': ['pytest', 'pytest-cov', 'pytest-xdist', 'ruff'],
-        'docs': ['mne', 'myst-parser', 'nibabel', 'pooch', 'tdqm',
-                 'sphinx', 'sphinx-gallery',
-                 'sphinx_bootstrap_theme', 'sphinx-copybutton',
-                 'pillow', 'numpydoc',
-                 ],
-        'gui': ['ipywidgets>=8.0.0', 'ipykernel', 'ipympl', 'voila', ],
+        'docs': ['mne', 'myst-parser', 'nibabel', 'numpydoc', 'pillow',
+                 'pooch', 'pydata-sphinx-theme', 'sphinx', 'sphinx-gallery',
+                 'sphinx-copybutton', 'tdqm'],
+        'gui': ['ipywidgets>=8.0.0', 'ipykernel', 'ipympl', 'voila'],
     }
     extras['dev'] = (extras['opt'] + extras['parallel'] + extras['test'] +
                      extras['docs'] + extras['gui'])