docs: switch to sphinx-design (#189)

* chore: switch to importlib-metadata in `conf.py` * ci: update pip constraints and pre-commit config * ci: update to `actions/setup-python@v4` Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: GitHub <[email protected]>
ComPWA · Jun 27, 2022 · 18a7a21 · 18a7a21
1 parent a23bdf7
commit 18a7a21
Show file tree

Hide file tree

Showing 15 changed files with 51 additions and 33 deletions.
diff --git a/.constraints/py3.10.txt b/.constraints/py3.10.txt
@@ -154,7 +154,7 @@ sphinx-book-theme==0.3.2
 sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
-sphinx-panels==0.6.0
+sphinx-design==0.2.0
 sphinx-thebe==0.1.2
 sphinx-togglebutton==0.3.1
 sphinxcontrib-applehelp==1.0.2

diff --git a/.constraints/py3.6.txt b/.constraints/py3.6.txt
@@ -53,7 +53,7 @@ identify==2.4.4
 idna==3.3
 imagesize==1.3.0
 immutables==0.18
-importlib-metadata==4.2.0
+importlib-metadata==4.2.0 ; python_version < "3.8.0"
 importlib-resources==3.0.0
 iniconfig==1.1.1
 ipykernel==5.5.6
@@ -153,7 +153,7 @@ sphinx-book-theme==0.2.0
 sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
-sphinx-panels==0.6.0
+sphinx-design==0.0.13
 sphinx-thebe==0.1.2
 sphinx-togglebutton==0.3.1
 sphinxcontrib-applehelp==1.0.2

diff --git a/.constraints/py3.7.txt b/.constraints/py3.7.txt
@@ -51,7 +51,7 @@ hepunits==2.2.0
 identify==2.5.1
 idna==3.3
 imagesize==1.3.0
-importlib-metadata==4.2.0
+importlib-metadata==4.2.0 ; python_version < "3.8.0"
 importlib-resources==5.8.0
 iniconfig==1.1.1
 ipykernel==6.15.0
@@ -156,7 +156,7 @@ sphinx-book-theme==0.3.2
 sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
-sphinx-panels==0.6.0
+sphinx-design==0.2.0
 sphinx-thebe==0.1.2
 sphinx-togglebutton==0.3.1
 sphinxcontrib-applehelp==1.0.2

diff --git a/.constraints/py3.8.txt b/.constraints/py3.8.txt
@@ -155,7 +155,7 @@ sphinx-book-theme==0.3.2
 sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
-sphinx-panels==0.6.0
+sphinx-design==0.2.0
 sphinx-thebe==0.1.2
 sphinx-togglebutton==0.3.1
 sphinxcontrib-applehelp==1.0.2

diff --git a/.constraints/py3.9.txt b/.constraints/py3.9.txt
@@ -154,7 +154,7 @@ sphinx-book-theme==0.3.2
 sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
-sphinx-panels==0.6.0
+sphinx-design==0.2.0
 sphinx-thebe==0.1.2
 sphinx-togglebutton==0.3.1
 sphinxcontrib-applehelp==1.0.2

diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -38,7 +38,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install dependencies

diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
@@ -20,7 +20,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3.8
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install dependencies

diff --git a/.github/workflows/ci-style.yml b/.github/workflows/ci-style.yml
@@ -17,7 +17,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3.8
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install dependencies

diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@master
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -71,7 +71,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml
@@ -20,7 +20,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3.8
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install dependencies

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -41,7 +41,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/ComPWA/repo-maintenance
-    rev: 0.0.131
+    rev: 0.0.132
     hooks:
       - id: check-dev-files
         args:

diff --git a/docs/_extend_docstrings.py b/docs/_extend_docstrings.py
@@ -46,17 +46,19 @@ def extend_create_isobar_topologies() -> None:
         lambda t: qrules.io.asdot(t, render_resonance_id=True),
         topologies,
     )
-    images = [_graphviz_to_image(dot, indent=6) for dot in dot_renderings]
+    images = [_graphviz_to_image(dot, indent=8) for dot in dot_renderings]
     _append_to_docstring(
         create_isobar_topologies,
         f"""
 
-    .. panels::
-      :body: text-center
-      {images[0]}
+    .. grid:: 1 2 2 2
+      :gutter: 2
 
-      ---
-      {images[1]}
+      .. grid-item-card::
+        {images[0]}
+
+      .. grid-item-card::
+        {images[1]}
     """,
     )
 
@@ -71,7 +73,7 @@ def extend_create_n_body_topology() -> None:
     dot = qrules.io.asdot(topology, render_initial_state_id=True)
     _append_to_docstring(
         create_n_body_topology,
-        _graphviz_to_image(dot, indent=4),
+        _graphviz_to_image(dot, indent=6),
     )
 
 
@@ -86,7 +88,7 @@ def extend_Topology() -> None:
     )
     _append_to_docstring(
         Topology,
-        _graphviz_to_image(dot, indent=4),
+        _graphviz_to_image(dot, indent=6),
     )
 
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -14,7 +14,6 @@
 
 # pyright: reportMissingImports=false
 import sphobjinv as soi
-from pkg_resources import get_distribution
 from pybtex.database import Entry
 from pybtex.plugin import register_plugin
 from pybtex.richtext import Tag, Text
@@ -31,6 +30,13 @@
     words,
 )
 
+if sys.version_info < (3, 8):
+    from importlib_metadata import PackageNotFoundError
+    from importlib_metadata import version as get_package_version
+else:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as get_package_version
+
 # -- Project information -----------------------------------------------------
 project = "QRules"
 PACKAGE = "qrules"
@@ -45,9 +51,11 @@
 if re.match(r"^\d+$", BRANCH):  # PR preview
     BRANCH = "stable"
 
-if os.path.exists(f"../src/{PACKAGE}/version.py"):
-    __RELEASE = get_distribution(PACKAGE).version
-    version = ".".join(__RELEASE.split(".")[:3])
+try:
+    __VERSION = get_package_version(PACKAGE)
+    version = ".".join(__VERSION.split(".")[:3])
+except PackageNotFoundError:
+    pass
 
 
 # -- Fetch logo --------------------------------------------------------------
@@ -150,7 +158,7 @@ def fetch_logo(url: str, output_path: str) -> None:
     "sphinx_codeautolink",
     "sphinx_comments",
     "sphinx_copybutton",
-    "sphinx_panels",
+    "sphinx_design",
     "sphinx_thebe",
     "sphinx_togglebutton",
     "sphinxcontrib.bibtex",
@@ -224,7 +232,6 @@ def fetch_logo(url: str, output_path: str) -> None:
     "show_toc_level": 2,
 }
 html_title = "Quantum number conservation rules"
-panels_add_bootstrap_css = False  # wider page width with sphinx-panels
 pygments_style = "sphinx"
 todo_include_todos = False
 viewcode_follow_imported_members = True

diff --git a/docs/install.md b/docs/install.md
@@ -8,22 +8,26 @@
 
 The fastest way of installing this package is through PyPI or Conda:
 
-:::{tabbed} PyPI
+::::{tab-set}
+
+:::{tab-item} PyPI
 
 ```shell
 python3 -m pip install qrules
 ```
 
 :::
 
-:::{tabbed} Conda
+:::{tab-item} Conda
 
 ```shell
 conda install -c conda-forge qrules
 ```
 
 :::
 
+::::
+
 This installs the [latest release](https://github.com/ComPWA/qrules/releases) that you
 can find on the [`stable`](https://github.com/ComPWA/qrules/tree/stable) branch.
 
@@ -64,7 +68,9 @@ Next, you install the project in editable mode with either
 [Conda](https://docs.conda.io) or [`pip`](https://pypi.org/project/pip). It's
 recommended to use Conda, because this also pins the version of Python.
 
-:::{tabbed} Conda
+::::{tab-set}
+
+:::{tab-item} Conda
 
 ```shell
 conda env create
@@ -75,7 +81,7 @@ This installs the project in a Conda environment following the definitions in
 
 :::
 
-:::{tabbed} PyPI
+:::{tab-item} PyPI
 
 1. **[Recommended]** Create a virtual environment with
    [`venv`](https://docs.python.org/3/library/venv.html) (see
@@ -93,6 +99,8 @@ This installs the project in a Conda environment following the definitions in
 
 :::
 
+::::
+
 See {ref}`compwa-org:develop:Updating` for how to update the dependencies when new
 commits come in.
 

diff --git a/setup.cfg b/setup.cfg
@@ -62,6 +62,7 @@ all =
 doc =
     %(viz)s
     jupyter
+    importlib-metadata; python_version <"3.8.0"
     myst-nb >=0.14; python_version >="3.8.0"  # nb_ configuration prefixes
     myst-nb <0.14; python_version <"3.8.0"
     nbclient >=0.5.5  # https://github.com/executablebooks/jupyter-book/issues/833
@@ -71,7 +72,7 @@ doc =
     sphinx-codeautolink[ipython]
     sphinx-comments
     sphinx-copybutton
-    sphinx-panels
+    sphinx-design
     sphinx-thebe
     sphinx-togglebutton
     sphinxcontrib-bibtex >=2