📚🎨👌 Change docs theme from RTD to pydata (#324)

It is 2025 and I'm tired of getting flash banged by our docs 😅 While the RTD theme served us for a long time, they do not offer a dark theme version. Whereas the [`pydata` theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html) offers both light and dark themes as well as a more modern look in general. While working on this I found a bug when running the link checker so I added a workaround here and opened a [PR upstream](pydata/pydata-sphinx-theme#2097) to fix it. ### Change summary - [📚🎨 Change docs theme from RTD to pydata](a85457a) - [📚🎨🩹 Fix mermaid edge and marker (arrow head) color in darkmode](9eb459a) - [📚✨ Add interrogate badge](3650143) - [🚇🩹 Workaround to fix pydata_sphinx_theme error on linkcheck](f5b35f9)
glotaran · Jan 18, 2025 · cf780e3 · cf780e3
1 parent de10ba2
commit cf780e3
Show file tree

Hide file tree

Showing 7 changed files with 51 additions and 15 deletions.
diff --git a/.gitignore b/.gitignore
@@ -95,7 +95,7 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 docs/api/
-docs/_static
+docs/_static/pygta_config.schema.json
 # documents generated by Sphinx.ext.autosummary
 docs/source/user_documentation/api/*
 # doc figures

diff --git a/README.md b/README.md
@@ -7,6 +7,7 @@
 
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![codecov](https://codecov.io/gh/glotaran/pyglotaran-extras/branch/main/graph/badge.svg?token=I6F412Y390)](https://codecov.io/gh/glotaran/pyglotaran-extras)
+[![interrogate](https://raw.githubusercontent.com/econchick/interrogate/acbfb5ad55046b3ac7549811b6d73ea8072e7568/tests/unit/fixtures/plastic/100.svg)](https://github.com/econchick/interrogate)
 [![Discord](https://img.shields.io/discord/883443835135475753.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/KfnEYRSTJx)
 
 Supplementary package for pyglotaran with (example) plotting code for use with the pyglotaran package.

diff --git a/docs/_static/css/mermaid_dark.css b/docs/_static/css/mermaid_dark.css
@@ -0,0 +1,10 @@
+/* Overwrite edge colors and arror marker color in dakr mode. in */
+html[data-theme="dark"] pre.mermaid {
+  & .marker {
+    fill: #e3e3e3 !important;
+    stroke: #e3e3e3 !important;
+  }
+  & .flowchart-link {
+    stroke: #e3e3e3 !important;
+  }
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,6 +24,10 @@
 
 pyglotaran_extras.create_config_schema(HERE/"_static")
 
+# Workaround for error caused by pydata-sphinx-theme==0.16.1 during link check
+# TODO: Remove workaround when fix is available
+(HERE / "_build/linkcheck/_static").mkdir(parents=True, exist_ok=True)
+
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -40,7 +44,7 @@
     "myst_nb",
     'sphinxcontrib.mermaid',
     "sphinx_copybutton",
-    "sphinx_rtd_theme",
+    "pydata_sphinx_theme",
 ]
 
 myst_fence_as_directive = ["mermaid"]
@@ -97,9 +101,6 @@
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
@@ -109,9 +110,34 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+image_gh_raw_base = "https://raw.githubusercontent.com/glotaran/pyglotaran/eb8a1ea0e4e0e499c829766a3298e79ea4975f58/docs/source/images"
+html_theme = "pydata_sphinx_theme"
+html_logo =f"{image_gh_raw_base}/pyglotaran_logo_light_theme.svg"
+html_favicon = f"{image_gh_raw_base}/pyglotaran_favicon_transparent.svg"
 html_theme_options = {
-    "navigation_depth": 7,
+    "pygments_dark_style": "monokai",
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/glotaran/pyglotaran-extras",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        }
+    ],
+    "logo": {
+        "text": "Pyglotaran-Extras",
+        "image_dark": f"{image_gh_raw_base}/pyglotaran_logo_dark_theme.svg",
+    },
+
+}
+# Hide empty sidebars
+# Ref.: https://github.com/pydata/pydata-sphinx-theme/issues/1662#issuecomment-1913672649
+html_sidebars = {
+    'installation': [],
+    'usage': [],
+    'contributing': [],
+    'changelog': [],
+    'config/project/subproject/config_docs': [],
 }
 
 # Theme options are theme-specific and customize the look and feel of a
@@ -124,7 +150,9 @@
 # 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_static_path = ["_static"]
-
+html_css_files = [
+    'css/mermaid_dark.css',
+]
 
 # -- Options for HTMLHelp output ---------------------------------------
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,10 +1,11 @@
-# Welcome to pyglotaran_extras's documentation!
+```{include} ../README.md
+
+```
 
 ```{toctree}
 :caption: 'Contents:'
 :maxdepth: 2
 
-readme
 installation
 usage
 config/project/subproject/config_docs

diff --git a/docs/readme.md b/docs/readme.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -53,11 +53,10 @@ optional-dependencies.docs = [
   "myst-nb>=1.1.1",                  # notebook docs
   "myst-parser>=0.12",
   "numpydoc>=0.8",
+  "pydata-sphinx-theme>=0.16.1",
   "sphinx>=3.2",
   "sphinx-copybutton>=0.3",
   "sphinx-last-updated-by-git>=0.3",
-  "sphinx-rtd-theme>=1.2",
-  "sphinxcontrib-jquery>=4.1",       # Needed for the search to work Ref.: https://github.com/readthedocs/sphinx_rtd_theme/issues/1434
   "sphinxcontrib-mermaid>=0.9.2",
 ]
 optional-dependencies.test = [