Inheritance Diagram Dark Mode Support (pydata#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 pydata#820

.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";