From d7bbb79e444db1f4f4d6337c6fc76ad391eb1ece Mon Sep 17 00:00:00 2001 From: Ogi Moore Date: Wed, 29 May 2024 08:40:08 -0400 Subject: [PATCH] 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 --- .github/workflows/CI.yml | 13 +++++++++ docs/conf.py | 14 +++++++++ docs/examples/graphviz.rst | 29 +++++++++++++++++++ docs/examples/index.rst | 1 + pyproject.toml | 22 ++++++++++---- readthedocs.yml | 2 ++ .../assets/styles/extensions/_graphviz.scss | 7 +++++ .../assets/styles/pydata-sphinx-theme.scss | 1 + 8 files changed, 83 insertions(+), 6 deletions(-) create mode 100644 docs/examples/graphviz.rst create mode 100644 src/pydata_sphinx_theme/assets/styles/extensions/_graphviz.scss diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 576b9273b..e28a333e9 100644 --- a/.github/workflows/CI.yml +++ b/.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: | diff --git a/docs/conf.py b/docs/conf.py index 75c3a43a2..71d00bcc0 100644 --- a/docs/conf.py +++ b/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")) diff --git a/docs/examples/graphviz.rst b/docs/examples/graphviz.rst new file mode 100644 index 000000000..47cd24c8c --- /dev/null +++ b/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 diff --git a/docs/examples/index.rst b/docs/examples/index.rst index 02044c891..8c728033a 100644 --- a/docs/examples/index.rst +++ b/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. diff --git a/pyproject.toml b/pyproject.toml index d1532b6b7..ebae2a5db 100644 --- a/pyproject.toml +++ b/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"] diff --git a/readthedocs.yml b/readthedocs.yml index 72526f538..5f057c9ae 100644 --- a/readthedocs.yml +++ b/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: diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_graphviz.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_graphviz.scss new file mode 100644 index 000000000..3b0bb509b --- /dev/null +++ b/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; +} diff --git a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss b/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss index afd184b2f..1b8ac9cdc 100644 --- a/src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss +++ b/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";