build: switch to sphinx-design (#158)

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

Hide file tree

Showing 10 changed files with 58 additions and 37 deletions.
diff --git a/.constraints/py3.7.txt b/.constraints/py3.7.txt
@@ -132,8 +132,8 @@ sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
 sphinx-data-viewer==0.1.2
+sphinx-design==0.2.0
 sphinx-issues==3.0.1
-sphinx-panels==0.6.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
@@ -135,8 +135,8 @@ sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
 sphinx-data-viewer==0.1.2
+sphinx-design==0.2.0
 sphinx-issues==3.0.1
-sphinx-panels==0.6.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
@@ -135,8 +135,8 @@ sphinx-codeautolink==0.11.0
 sphinx-comments==0.0.3
 sphinx-copybutton==0.5.0
 sphinx-data-viewer==0.1.2
+sphinx-design==0.2.0
 sphinx-issues==3.0.1
-sphinx-panels==0.6.0
 sphinx-thebe==0.1.2
 sphinx-togglebutton==0.3.1
 sphinxcontrib-applehelp==1.0.2

diff --git a/.github/workflows/ci-style.yml b/.github/workflows/ci-style.yml
@@ -17,7 +17,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - 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
@@ -20,7 +20,7 @@ jobs:
           git diff --name-only origin/$GITHUB_BASE_REF --output=diff.txt -- docs/**.ipynb
           echo "::set-output name=modified-notebooks::$(cat diff.txt)"
       - run: cat diff.txt
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
         if: steps.diff.outputs.modified-notebooks != ''
         with:
           python-version: "3.8"

diff --git a/.github/workflows/notebooks.yml b/.github/workflows/notebooks.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@master
-      - uses: actions/setup-python@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: "3.8"
       - name: Install dependencies

diff --git a/docs/about.md b/docs/about.md
@@ -16,63 +16,77 @@ intended to bring theory and code closer together. The PWA Pages takes that one
 further: it is an independent and easy-to-maintain documentation project that can serve
 as a central place to gather links to PWA theory and software.
 
-:::{panels}
+<!-- prettier-ignore -->
+::::{grid} 1 2 2 2
+:gutter: 2
 
-```{link-button} https://github.com/ComPWA/qrules
-:text: QRules
-:classes: btn-block btn-outline-primary font-weight-bold
+:::{grid-item-card}
+
+```{button-link} https://github.com/ComPWA/qrules
+:color: primary
+:outline:
+QRules
 ```
 
-^^^^^^^
+:::
+
+:::{grid-item-card}
 
 [![Documentation build status](https://readthedocs.org/projects/qrules/badge/?version=latest)](https://qrules.readthedocs.io)
 [![10.5281/zenodo.5526360](https://zenodo.org/badge/doi/10.5281/zenodo.5526360.svg)](https://doi.org/10.5281/zenodo.5526360)
 [![PyPI package](https://img.shields.io/pypi/pyversions/qrules)](https://pypi.org/project/qrules)
 [![Conda package](https://anaconda.org/conda-forge/qrules/badges/version.svg)](https://anaconda.org/conda-forge/qrules)<br>
 Rule-based particle reaction problem solver on a quantum number level
 
----
+:::
+
+:::{grid-item-card}
 
-```{link-button} https://github.com/ComPWA/ampform
-:text: AmpForm
-:classes: btn-block btn-outline-primary font-weight-bold
+```{button-link} https://github.com/ComPWA/ampform
+:color: primary
+:outline:
+AmpForm
 ```
 
-^^^^^^^
 [![Documentation build status](https://readthedocs.org/projects/ampform/badge/?version=latest)](https://ampform.readthedocs.io)
 [![10.5281/zenodo.5526648](https://zenodo.org/badge/doi/10.5281/zenodo.5526648.svg)](https://doi.org/10.5281/zenodo.5526648)
 [![PyPI package](https://img.shields.io/pypi/pyversions/ampform)](https://pypi.org/project/ampform)
 [![Conda package](https://anaconda.org/conda-forge/ampform/badges/version.svg)](https://anaconda.org/conda-forge/ampform)<br>
 Automatically generate symbolic amplitude models for Partial Wave Analysis
 
----
+:::
 
-```{link-button} https://github.com/ComPWA/tensorwaves
-:text: TensorWaves
-:classes: btn-block btn-outline-primary font-weight-bold
+:::{grid-item-card}
+
+```{button-link} https://github.com/ComPWA/tensorwaves
+:color: primary
+:outline:
+TensorWaves
 ```
 
-^^^^^^^
 [![Documentation build status](https://readthedocs.org/projects/tensorwaves/badge/?version=latest)](https://tensorwaves.readthedocs.io)
 [![10.5281/zenodo.5526650](https://zenodo.org/badge/doi/10.5281/zenodo.5526650.svg)](https://doi.org/10.5281/zenodo.5526650)
 [![PyPI package](https://img.shields.io/pypi/pyversions/tensorwaves)](https://pypi.org/project/tensorwaves)
 [![Conda package](https://anaconda.org/conda-forge/tensorwaves/badges/version.svg)](https://anaconda.org/conda-forge/tensorwaves)<br>
 Python fitter package for multiple computational back-ends
 
----
+:::
 
-```{link-button} https://github.com/ComPWA/PWA-pages
-:text: PWA Pages
-:classes: btn-block btn-outline-primary font-weight-bold
-```
+:::{grid-item-card}
 
-^^^^^^^
+```{button-link} https://github.com/ComPWA/PWA-pages
+:color: primary
+:outline:
+PWA Pages
+```
 
 [![Documentation build status](https://readthedocs.org/projects/pwa/badge/?version=latest)](https://pwa.readthedocs.io)<br>
 A central knowledge-base for Partial Wave Analysis theory and software
 
 :::
 
+::::
+
 Finally, the {doc}`technical reports </reports>` on these pages
 ([compwa-org.rtfd.io](https://compwa-org.readthedocs.io)) describe more general tips and
 tricks, some of which can be of interest to general Python users as well!

diff --git a/docs/conf.py b/docs/conf.py
@@ -84,7 +84,7 @@ def fetch_logo(url: str, output_path: str) -> None:
     "sphinx_comments",
     "sphinx_copybutton",
     "sphinx_issues",
-    "sphinx_panels",
+    "sphinx_design",
     "sphinx_thebe",
     "sphinx_togglebutton",
     "sphinxcontrib.bibtex",
@@ -149,7 +149,6 @@ def fetch_logo(url: str, output_path: str) -> None:
     "show_toc_level": 2,
 }
 html_title = "Common Partial Wave Analysis Project"
-panels_add_bootstrap_css = False  # wider pages
 pygments_style = "sphinx"
 todo_include_todos = False
 viewcode_follow_imported_members = True

diff --git a/docs/develop.md b/docs/develop.md
@@ -8,10 +8,12 @@ This page describes some of the tools and conventions followed by
 [source code of the AmpForm repository](https://github.com/ComPWA/AmpForm) as example,
 because its file structure is comparable to that of other ComPWA repositories.
 
-::::{tip} To start developing, simply run the following from a cloned repository on your
-machine:
+:::::{tip} To start developing, simply run the following from a cloned repository on
+your machine:
 
-:::{tabbed} Conda
+::::{tab-set}
+
+:::{tab-item} Conda
 
 ```shell
 conda env create
@@ -21,7 +23,7 @@ pre-commit install
 
 :::
 
-:::{tabbed} Python venv
+:::{tab-item} Python venv
 
 ```shell
 python3 -m venv ./venv
@@ -34,9 +36,11 @@ Replace `3.8` with the Python version you use on your machine.
 
 :::
 
+::::
+
 See {ref}`develop:Virtual environment` for more info.
 
-::::
+:::::
 
 ## Local set-up
 
@@ -54,7 +58,9 @@ and [Python's built-in `venv`](https://docs.python.org/3/tutorial/venv.html). In
 case, you have to activate the environment whenever you want to run the framework or use
 the developer tools.
 
-:::{tabbed} Conda environment
+::::{tab-set}
+
+:::{tab-item} Conda environment
 
 [Conda/Anaconda](https://www.anaconda.com) can be installed without administrator
 rights, see instructions on
@@ -80,7 +86,7 @@ In addition, it will install the framework itself in
 
 :::
 
-:::{tabbed} Python venv
+:::{tab-item} Python venv
 
 If you have [Python's `venv`](https://docs.python.org/3/library/venv.html), available on
 your system, you can create a virtual environment with it. Navigate to some convenient
@@ -107,6 +113,8 @@ pip install -e .
 
 :::
 
+::::
+
 ### Editable installation
 
 When developing a package, it is most convenient if you install it in

diff --git a/setup.cfg b/setup.cfg
@@ -46,7 +46,7 @@ doc =
     sphinx-comments
     sphinx-copybutton
     sphinx-issues
-    sphinx-panels
+    sphinx-design
     sphinx-thebe
     sphinx-togglebutton
     sphinxcontrib-bibtex >=2