DOC: modernize website layout and theme (#21)

* DX: switch to Python 3.9 in developer environment

.pre-commit-config.yaml

@@ -12,8 +12,33 @@ repos:
       - id: check-hooks-apply
       - id: check-useless-excludes
 
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.6.1
+    hooks:
+      - id: nbstripout
+        args:
+          - --extra-keys
+          - |
+            cell.attachments
+            cell.metadata.code_folding
+            cell.metadata.id
+            cell.metadata.pycharm
+            cell.metadata.user_expressions
+            metadata.celltoolbar
+            metadata.colab.name
+            metadata.colab.provenance
+            metadata.interpreter
+            metadata.notify_time
+            metadata.toc
+            metadata.toc-autonumbering
+            metadata.toc-showcode
+            metadata.toc-showmarkdowntxt
+            metadata.toc-showtags
+            metadata.varInspector
+            metadata.vscode
+
   - repo: https://github.com/ComPWA/policy
-    rev: 0.2.0
+    rev: 0.2.3
     hooks:
       - id: check-dev-files
         args:
@@ -47,6 +72,23 @@ repos:
         args: [--line-length=85]
         types_or: [jupyter]
 
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+
+  - repo: https://github.com/ComPWA/mirrors-taplo
+    rev: v0.8.1
+    hooks:
+      - id: taplo
+
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.23.1
+    hooks:
+      - id: toml-sort
+        args:
+          - --in-place
+
   - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
     rev: 2.7.3
     hooks:
@@ -58,36 +100,6 @@ repos:
             .*\.py
           )$
 
-  - repo: https://github.com/kynan/nbstripout
-    rev: 0.6.1
-    hooks:
-      - id: nbstripout
-        args:
-          - --extra-keys
-          - |
-            cell.attachments
-            cell.metadata.code_folding
-            cell.metadata.id
-            cell.metadata.pycharm
-            cell.metadata.user_expressions
-            metadata.celltoolbar
-            metadata.colab.name
-            metadata.colab.provenance
-            metadata.interpreter
-            metadata.notify_time
-            metadata.toc
-            metadata.toc-autonumbering
-            metadata.toc-showcode
-            metadata.toc-showmarkdowntxt
-            metadata.toc-showtags
-            metadata.varInspector
-            metadata.vscode
-
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
-    hooks:
-      - id: prettier
-
   - repo: https://github.com/ComPWA/mirrors-pyright
     rev: v1.1.345
     hooks:
@@ -99,15 +111,3 @@ repos:
       - id: ruff
         args: [--fix]
         types_or: [python, pyi, jupyter]
-
-  - repo: https://github.com/ComPWA/mirrors-taplo
-    rev: v0.8.1
-    hooks:
-      - id: taplo
-
-  - repo: https://github.com/pappasam/toml-sort
-    rev: v0.23.1
-    hooks:
-      - id: toml-sort
-        args:
-          - --in-place

docs/conf.py

@@ -1,68 +1,19 @@
-"""Configuration file for the Sphinx documentation builder.
-
-This file only contains a selection of the most common options. For a full list see the
-documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html
-"""
-
 from __future__ import annotations
 
-import contextlib
-import os
-import re
-
-import requests
+from sphinx_api_relink.helpers import get_branch_name, get_execution_mode
 
-# -- Project information -----------------------------------------------------
-project = "ComPWA benchmarks"
+BRANCH = get_branch_name()
+ORGANIZATION = "ComPWA"
 PACKAGE = "benchmarks"
 REPO_NAME = "benchmarks"
-copyright = "2022, ComPWA"  # noqa: A001
-author = "Common Partial Wave Analysis"
-
-
-def get_branch_name() -> str:
-    branch_name = os.environ.get("READTHEDOCS_VERSION", "stable")
-    if branch_name == "latest":
-        return "main"
-    if re.match(r"^\d+$", branch_name):  # PR preview
-        return "stable"
-    return branch_name
-
-
-def get_logo_path() -> str | None:
-    path = "_static/logo.svg"
-    with contextlib.suppress(requests.exceptions.ConnectionError):
-        _fetch_logo(
-            url="https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg",
-            output_path=path,
-        )
-    if os.path.exists(path):
-        return path
-    return None
-
-
-def get_nb_execution_mode() -> str:
-    if "FORCE_EXECUTE_NB" in os.environ:
-        print("\033[93;1mWill run ALL Jupyter notebooks!\033[0m")
-        return "force"
-    if "EXECUTE_NB" in os.environ:
-        return "cache"
-    return "off"
-
-
-def _fetch_logo(url: str, output_path: str) -> None:
-    if os.path.exists(output_path):
-        return
-    online_content = requests.get(url, allow_redirects=True)
-    with open(output_path, "wb") as stream:
-        stream.write(online_content.content)
+REPO_TITLE = "ComPWA benchmarks"
 
 
 autosectionlabel_prefix_document = True
 codeautolink_concat_default = True
 copybutton_prompt_is_regexp = True
-copybutton_prompt_text = r">>> |\.\.\. "  # doctest
-default_role = "py:obj"
+copybutton_prompt_text = r">>> |\.\.\. "
+copyright = f"2024, {ORGANIZATION}"  # noqa: A001
 exclude_patterns = [
     "**.ipynb_checkpoints",
     "*build",
@@ -81,32 +32,60 @@ def _fetch_logo(url: str, output_path: str) -> None:
 html_copy_source = True  # needed for download notebook button
 html_favicon = "_static/favicon.ico"
 html_last_updated_fmt = "%-d %B %Y"
-html_logo = get_logo_path()
+html_logo = (
+    "https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg"
+)
 html_show_copyright = False
 html_show_sourcelink = False
 html_show_sphinx = False
 html_sourcelink_suffix = ""
 html_static_path = ["_static"]
 html_theme = "sphinx_book_theme"
 html_theme_options = {
-    "logo": {"text": project},
-    "repository_url": f"https://github.com/ComPWA/{REPO_NAME}",
-    "repository_branch": get_branch_name(),
-    "path_to_docs": "docs",
-    "use_download_button": True,
-    "use_edit_page_button": True,
-    "use_issues_button": True,
-    "use_repository_button": True,
+    "icon_links": [
+        {
+            "name": "Common Partial Wave Analysis",
+            "url": "https://compwa.github.io",
+            "icon": "https://compwa.github.io/_static/favicon.ico",
+            "type": "url",
+        },
+        {
+            "name": "GitHub",
+            "url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Launch on Binder",
+            "url": f"https://mybinder.org/v2/gh/{ORGANIZATION}/{REPO_NAME}/{BRANCH}?filepath=docs",
+            "icon": "https://mybinder.readthedocs.io/en/latest/_static/favicon.png",
+            "type": "url",
+        },
+        {
+            "name": "Launch on Colaboratory",
+            "url": f"https://colab.research.google.com/github/{ORGANIZATION}/{REPO_NAME}/blob/{BRANCH}",
+            "icon": "https://avatars.githubusercontent.com/u/33467679?s=100",
+            "type": "url",
+        },
+    ],
     "launch_buttons": {
         "binderhub_url": "https://mybinder.org",
         "colab_url": "https://colab.research.google.com",
         "deepnote_url": "https://deepnote.com",
         "notebook_interface": "jupyterlab",
     },
+    "logo": {"text": REPO_TITLE},
+    "path_to_docs": "docs",
+    "repository_branch": BRANCH,
+    "repository_url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}",
     "show_navbar_depth": 2,
     "show_toc_level": 2,
+    "use_download_button": False,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+    "use_source_button": True,
 }
-html_title = project
+html_title = REPO_TITLE
 intersphinx_mapping = {
     "matplotlib": ("https://matplotlib.org/stable", None),
     "numpy": ("https://numpy.org/doc/stable", None),
@@ -121,7 +100,7 @@ def _fetch_logo(url: str, output_path: str) -> None:
 ]
 myst_linkify_fuzzy_links = False
 myst_update_mathjax = False
-nb_execution_mode = get_nb_execution_mode()
+nb_execution_mode = get_execution_mode()
 nb_execution_show_tb = True
 nb_execution_timeout = -1
 nb_output_stderr = "remove"
@@ -134,4 +113,4 @@ def _fetch_logo(url: str, output_path: str) -> None:
 ]
 nitpicky = True  # warn if cross-references are missing
 primary_domain = "py"
-pygments_style = "sphinx"
+project = REPO_TITLE

docs/index.md

@@ -4,7 +4,7 @@
 
 ```
 
-These webpages are a visualization of the benchmark scripts provided in the https://github.com/ComPWA/benchmarks repositories.
+These webpages are a visualization of the benchmark scripts provided in the [github.com/ComPWA/benchmarks](https://github.com/ComPWA/benchmarks) repository.
 
 ```{toctree}
 ---

environment.yml

@@ -2,9 +2,9 @@ name: benchmarks
 channels:
   - defaults
 dependencies:
-  - python==3.8.*
+  - python==3.9.*
   - pip
   - pip:
       - -e .[dev]
 variables:
-  PRETTIER_LEGACY_CLI: "1"
+  PRETTIER_LEGACY_CLI: 1

pyproject.toml

@@ -47,6 +47,7 @@ doc = [
     "myst-nb >=0.14", # nb_ configuration prefixes
     "myst-parser[linkify]",
     "pandas",
+    "sphinx-api-relink",
     "sphinx-book-theme",
     "sphinx-codeautolink[ipython]",
     "sphinx-copybutton",
@@ -73,11 +74,15 @@ lint = [
 sty = [
     "benchmarks[format]",
     "benchmarks[lint]",
+    "benchmarks[types]",
     "pre-commit >=1.4.0",
 ]
 test = [
     "nbmake",
 ]
+types = [
+    "sphinx-api-relink",
+]
 
 [project.readme]
 content-type = "text/markdown"