Inheritance Diagram Dark Mode Support (#1834)

Apply CSS filtering to have the inheritance diagram conform to dark mode, and add a example demonstrating inheritance diagram in kitchensink.. 

We also install graphviz on CI to test this. 

The css will only apply to inheritance diagram and not to all graphviz output.

Addresses #820

Author: j9ac9k

.github/workflows/CI.yml

@@ -145,6 +145,19 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           pandoc: true
+      - name: "Install Graphviz on Windows 🗔"
+        if: runner.os == 'Windows'
+        run: choco install graphviz
+      - name: "Install Graphviz on macOS "
+        if: runner.os == 'macOS'
+        run: |
+          brew update
+          brew install graphviz
+      - name: "Install Graphviz on Linux 🐧"
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends graphviz
       - name: "Build docs and check for warnings 📖"
         shell: bash
         run: |

docs/conf.py

@@ -31,6 +31,8 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.graphviz",
     "sphinxext.rediraffe",
     "sphinx_design",
     "sphinx_copybutton",
@@ -60,6 +62,8 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
+intersphinx_mapping = {"sphinx": ("https://www.sphinx-doc.org/en/master", None)}
+
 # -- Sitemap -----------------------------------------------------------------
 
 # ReadTheDocs has its own way of generating sitemaps, etc.
@@ -90,6 +94,16 @@
     "jupyter": ("Jupyter", "https://jupyter.org"),
 }
 
+
+# -- sphinx_ext_graphviz options ---------------------------------------------
+
+graphviz_output_format = "svg"
+inheritance_graph_attrs = dict(
+    rankdir="LR",
+    fontsize=14,
+    ratio="compress",
+)
+
 # -- sphinx_togglebutton options ---------------------------------------------
 togglebutton_hint = str(_("Click to expand"))
 togglebutton_hint_hide = str(_("Click to collapse"))

docs/examples/graphviz.rst

@@ -0,0 +1,29 @@
+========
+Graphviz
+========
+
+Inheritance Diagram
+-------------------
+
+If you use :mod:`sphinx.ext.inheritance_diagram` to generate inheritance diagrams with
+:mod:`sphinx.ext.graphviz`, and you output the inheritance diagrams in SVG format,
+they will automatically adapt to this theme's light or dark mode.
+
+To have the inheritance-diagram render to SVG, inside ``conf.py``, you need
+the following option.
+
+.. code-block:: python
+
+    # conf.py
+    ...
+    graphviz_output_format = 'svg'
+    ...
+
+Below is an example of the inheritance diagram for ``matplotlib.figure.Figure``.
+Try toggling light/dark mode to see it adapt!
+
+.. inheritance-diagram:: matplotlib.figure.Figure
+
+See the sphinx inheritance-diagram `documentation`_ for more information.
+
+.. _documentation: https://www.sphinx-doc.org/en/master/usage/extensions/inheritance.html

docs/examples/index.rst

@@ -18,6 +18,7 @@ See the sections in the primary sidebar and below to explore.
     kitchen-sink/index
     pydata
     execution
+    graphviz
 
 
 .. Note: the caption below is intentionally long in order to test out what long captions look like.

pyproject.toml

@@ -1,5 +1,7 @@
 [build-system]
-requires = ["sphinx-theme-builder @ https://github.com/pradyunsg/sphinx-theme-builder/archive/87214d0671c943992c05e3db01dca997e156e8d6.zip"]
+requires = [
+  "sphinx-theme-builder @ https://github.com/pradyunsg/sphinx-theme-builder/archive/87214d0671c943992c05e3db01dca997e156e8d6.zip",
+]
 build-backend = "sphinx_theme_builder"
 
 [tool.sphinx-theme-builder]
@@ -10,7 +12,7 @@ additional-compiled-static-assets = [
   "vendor/",
   "styles/bootstrap.css",
   "scripts/bootstrap.js",
-  "locale/"
+  "locale/",
 ]
 
 [project]
@@ -27,7 +29,7 @@ dependencies = [
   "Babel",
   "pygments>=2.7",
   "accessible-pygments",
-  "typing-extensions"
+  "typing-extensions",
 ]
 license = { file = "LICENSE" }
 maintainers = [
@@ -52,7 +54,7 @@ classifiers = [
 [project.optional-dependencies]
 doc = [
   "numpydoc",
-  "linkify-it-py", # for link shortening
+  "linkify-it-py",         # for link shortening
   "rich",
   "sphinxext-rediraffe",
   "sphinx-sitemap",
@@ -76,10 +78,18 @@ doc = [
   "nbsphinx",
   "ipyleaflet",
   "colorama",
-  "ipywidgets"
+  "ipywidgets",
+  "graphviz",
 ]
 test = ["pytest", "pytest-cov", "pytest-regressions", "sphinx[test]"]
-dev = ["pyyaml", "pre-commit", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
+dev = [
+  "pyyaml",
+  "pre-commit",
+  "pydata-sphinx-theme[doc,test]",
+  "tox",
+  "pandoc",
+  "sphinx-theme-builder[cli]",
+]
 a11y = ["pytest-playwright"]
 i18n = ["Babel", "jinja2"]
 

readthedocs.yml

@@ -7,6 +7,8 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.10"
+  apt_packages:
+    - graphviz
   jobs:
     # build the gallery of themes before building the doc
     post_install:

src/pydata_sphinx_theme/assets/styles/extensions/_graphviz.scss

@@ -0,0 +1,7 @@
+/* Styles for graphviz generated output from Sphinx */
+
+/* Style the inheritance diagram such that it has a dark mode */
+html[data-theme="dark"] div.graphviz > object.inheritance {
+  filter: brightness(0.8) invert(0.82) contrast(1.2);
+  color-scheme: normal;
+}

src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss

@@ -68,6 +68,7 @@
 @import "./extensions/copybutton";
 @import "./extensions/ethical-ads";
 @import "./extensions/execution";
+@import "./extensions/graphviz";
 @import "./extensions/pydata";
 @import "./extensions/sphinx_design";
 @import "./extensions/togglebutton";