From b12fd84fc0d71ad72b2664241751d0306ed5cc5b Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Mon, 27 Jun 2022 16:27:31 +0200 Subject: [PATCH] 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 --- .constraints/py3.7.txt | 2 +- .constraints/py3.8.txt | 2 +- .constraints/py3.9.txt | 2 +- .github/workflows/ci-style.yml | 2 +- .github/workflows/ci-tests.yml | 2 +- .github/workflows/notebooks.yml | 2 +- docs/about.md | 56 ++++++++++++++++++++------------- docs/conf.py | 3 +- docs/develop.md | 22 ++++++++----- setup.cfg | 2 +- 10 files changed, 58 insertions(+), 37 deletions(-) diff --git a/.constraints/py3.7.txt b/.constraints/py3.7.txt index 3ebc709e..6367ba72 100644 --- 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 index 6038e678..1e84fcc5 100644 --- 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 index 3e99481c..54cba3ff 100644 --- 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 index 97eed894..94dae3bd 100644 --- 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 index f5e904e5..2de4f9ef 100644 --- 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 index 640c6265..b7e2fd24 100644 --- 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 index be3bff2c..6a4c5638 100644 --- a/docs/about.md +++ b/docs/about.md @@ -16,14 +16,21 @@ 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} + +::::{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) @@ -31,48 +38,55 @@ as a central place to gather links to PWA theory and software. [![Conda package](https://anaconda.org/conda-forge/qrules/badges/version.svg)](https://anaconda.org/conda-forge/qrules)
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)
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)
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)
A central knowledge-base for Partial Wave Analysis theory and software ::: +:::: + Finally, the {doc}`technical 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 index 8a99cbe0..bd618768 100644 --- 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 index 50bea100..ba096175 100644 --- 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 index a28c9e04..9d369b27 100644 --- 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