[no ci] docs: change theme to PyData Sphinx theme

Author: vpratz

docsrc/poly.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 import logging
 from pathlib import Path
-from docsrc.polyversion_patches import DynamicPip, CustomDriver
+from docsrc.polyversion_patches import DynamicPip, CustomDriver, PyDataVersionEncoder
 
 from sphinx_polyversion.api import apply_overrides
 from sphinx_polyversion.git import Git, GitRef, GitRefType, file_predicate, refs_by_type
@@ -50,7 +50,7 @@
     "numpydoc",
     "myst-nb",
     "sphinx_design",
-    "sphinx-book-theme",
+    "pydata-sphinx-theme",
     "sphinxcontrib-bibtex",
     "sphinx-polyversion==1.1.0",
 ]
@@ -162,6 +162,7 @@ async def selector(rev, keys):
         pre_cmd=["python", root / src / "pre-build.py", Placeholder.SOURCE_DIR],
     ),
     env=ENVIRONMENT,
+    encoder=PyDataVersionEncoder(),
     selector=selector,
     template_dir=root / src / "polyversion/templates",
     static_dir=root / src / "polyversion/static",

docsrc/polyversion_patches.py

@@ -1,4 +1,5 @@
 import asyncio
+import json
 import logging
 import os
 from pathlib import Path
@@ -8,6 +9,9 @@
 from sphinx_polyversion.builder import BuildError
 from sphinx_polyversion.driver import DefaultDriver
 from sphinx_polyversion.pyvenv import Pip
+from sphinx_polyversion.json import JSONable
+
+from typing import Iterator
 
 import tempfile
 
@@ -64,6 +68,35 @@ async def __aenter__(self):
         return self
 
 
+class PyDataVersionEncoder(json.JSONEncoder):
+    """Encoder to turn list of built GitRefs into a version.json consumable by Sphinx."""
+
+    def transform(self, o: JSONable):
+        output = []
+        processed_names = []
+        for ref in o:
+            if ref.name in processed_names:
+                continue
+            output.append(
+                {
+                    "name": ref.name,
+                    "version": ref.name,
+                    "url": f"/{ref.name}",
+                }
+            )
+            processed_names.append(ref.name)
+        # do not use cast for performance reasons
+        return output
+
+    def __call__(self, o: JSONable):
+        return self.transform(o)
+
+    def iterencode(self, o: JSONable, _one_shot: bool = False) -> Iterator[str]:
+        """Encode an object."""
+        # called for every top level object to encode
+        return super().iterencode(self.transform(o), _one_shot)
+
+
 class CustomDriver(DefaultDriver):
     """DefaultDriver which does not copy venvs for local builds.
 
@@ -101,9 +134,10 @@ async def get_unignored_files(directory: Path) -> list[Path]:
                 for filename in files:
                     source = self.root / filename
                     target = path / filename
-                    target.parent.mkdir(parents=True, exist_ok=True)
-                    if not target.exists():
-                        shutil.copy2(source, target, follow_symlinks=False)
+                    if source.exists():
+                        target.parent.mkdir(parents=True, exist_ok=True)
+                        if not target.exists():
+                            shutil.copy2(source, target, follow_symlinks=False)
             except CalledProcessError:
                 logger.warning("Could not list un-ignored files using git. Copying full working directory...")
                 shutil.copytree(self.root, path, symlinks=True, dirs_exist_ok=True)

docsrc/source/_static/bayesflow_hor_dark.png

@@ -20,8 +20,3 @@
 .bd-sidebar-primary div#rtd-footer-container {
   margin: 0;
 }
-
-ul.bd-breadcrumbs {
-  margin-top: -1rem;
-  margin-bottom: 0.5rem;
-}

docsrc/source/_static/custom.css

@@ -58,7 +58,7 @@
 ]
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/{.major}".format(sys.version_info), None),
+    "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "matplotlib": ("https://matplotlib.org/", None),
@@ -106,7 +106,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_book_theme"
+html_theme = "pydata_sphinx_theme"
 html_title = "BayesFlow: Amortized Bayesian Inference"
 
 # Add any paths that contain custom _static files (such as style sheets) here,
@@ -116,27 +116,29 @@
 html_css_files = ["custom.css"]
 html_show_sourcelink = False
 html_theme_options = {
-    "repository_url": "https://github.com/bayesflow-org/bayesflow",
-    "repository_branch": current,
     "use_edit_page_button": True,
-    "use_issues_button": True,
-    "use_repository_button": True,
-    "use_download_button": True,
-    "logo": {"alt-text": "BayesFlow"},
+    "logo": {
+        "alt-text": "BayesFlow",
+        "image_light": "_static/bayesflow_hor.png",
+        "image_dark": "_static/bayesflow_hor_dark.png",
+    },
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    "switcher": {
+        "json_url": "/versions.json",
+        "version_match": current,
+    },
+    "check_switcher": False,
+}
+html_context = {
+    "github_url": "https://github.com",  # or your GitHub Enterprise site
+    "github_user": "bayesflow-org",
+    "github_repo": "bayesflow",
+    "github_version": current,
+    "doc_path": "docsrc",
 }
 html_logo = "_static/bayesflow_hor.png"
 html_favicon = "_static/bayesflow_hex.ico"
 html_baseurl = "https://www.bayesflow.org/"
-html_js_files = ["https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"]
-html_sidebars = {
-    "**": [
-        "navbar-logo.html",
-        "icon-links.html",
-        "search-button-field.html",
-        "sbt-sidebar-nav.html",
-        "versioning.html",
-    ],
-}
 
 todo_include_todos = True
 

docsrc/source/_templates/layout.html

@@ -117,7 +117,6 @@ Indices
     :titlesonly:
     :hidden:
 
-    self
     examples
     api/bayesflow
     about
@@ -126,6 +125,7 @@ Indices
 .. toctree::
     :maxdepth: 1
     :caption: Development
+    :hidden:
 
-    contributing
-    development/index
+    Contributing <contributing>
+    Developer docs <development/index>

docsrc/source/conf.py

@@ -39,7 +39,7 @@ docs = [
   "numpydoc",
   "myst-nb",
   "sphinx_design",
-  "sphinx-book-theme",
+  "pydata-sphinx-theme",
   "sphinxcontrib-bibtex",
   "sphinx-polyversion==1.1.0",
 ]