From 5a9c6869a6f2c2ec5fd1e65c387eae2181628900 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Sat, 9 Dec 2023 13:15:16 +0100 Subject: [PATCH] MAINT: update pip constraints and pre-commit (#509) * DX: gitignore `.jupyter_ystore.db` This is a file produced by `jupyter-collaboration` * DX: gitignore `oryx-build-commands.txt` Produced when running on GitHub Codespaces * MAINT: clean up `conf.py` with new Sphinx extensions * MAINT: remove `ypy-websocket` version constraints --------- Co-authored-by: GitHub Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .constraints/py3.10.txt | 34 ++-- .constraints/py3.11.txt | 34 ++-- .constraints/py3.8.txt | 28 ++- .constraints/py3.9.txt | 34 ++-- .cspell.json | 1 + .gitignore | 2 + .gitpod.yml | 1 + .pre-commit-config.yaml | 48 ++--- .readthedocs.yml | 4 +- .vscode/settings.json | 2 +- docs/_relink_references.py | 106 ---------- docs/conf.py | 370 ++++++++++++---------------------- environment.yml | 4 +- pyproject.toml | 11 +- tests/data/test_phasespace.py | 4 +- 15 files changed, 227 insertions(+), 456 deletions(-) delete mode 100644 docs/_relink_references.py diff --git a/.constraints/py3.10.txt b/.constraints/py3.10.txt index 45ac36d4..5ed3be18 100644 --- a/.constraints/py3.10.txt +++ b/.constraints/py3.10.txt @@ -52,19 +52,19 @@ fqdn==1.5.1 gast==0.5.4 gitdb==4.0.11 gitpython==3.1.40 -google-auth==2.24.0 +google-auth==2.25.2 google-auth-oauthlib==1.1.0 google-pasta==0.2.0 graphviz==0.20.1 -greenlet==3.0.1 -grpcio==1.59.3 +greenlet==3.0.2 +grpcio==1.60.0 h5py==3.10.0 hepunits==2.3.2 -identify==2.5.32 +identify==2.5.33 idna==3.6 imagesize==1.4.1 iminuit==2.24.0 -importlib-metadata==6.9.0 +importlib-metadata==7.0.0 iniconfig==2.0.0 ipykernel==6.27.1 ipympl==0.9.3 @@ -73,8 +73,8 @@ ipython-genutils==0.2.0 ipywidgets==8.1.1 isoduration==20.11.0 isort==5.12.0 -jax==0.4.20 -jaxlib==0.4.20 +jax==0.4.21 +jaxlib==0.4.21 jedi==0.19.1 jinja2==3.1.2 json5==0.9.14 @@ -88,7 +88,7 @@ jupyter-console==6.6.3 jupyter-core==5.5.0 jupyter-events==0.9.0 jupyter-lsp==2.2.1 -jupyter-server==2.11.1 +jupyter-server==2.12.1 jupyter-server-mathjax==0.2.6 jupyter-server-terminals==0.4.4 jupyterlab==4.0.9 @@ -120,7 +120,7 @@ mypy-extensions==1.0.0 myst-nb==1.0.0 myst-parser==2.0.0 nbclient==0.6.8 -nbconvert==7.11.0 +nbconvert==7.12.0 nbdime==4.0.1 nbformat==5.9.2 nbmake==1.4.6 @@ -134,7 +134,7 @@ oauthlib==3.2.2 opt-einsum==3.3.0 overrides==7.4.0 packaging==23.2 -pandas==2.1.3 +pandas==2.1.4 pandocfilters==1.5.0 parso==0.8.3 particle==0.23.1 @@ -142,7 +142,7 @@ pathspec==0.11.2 pexpect==4.9.0 phasespace==1.9.0 pillow==10.1.0 -platformdirs==4.0.0 +platformdirs==4.1.0 pluggy==1.3.0 pre-commit==3.5.0 prometheus-client==0.19.0 @@ -173,11 +173,11 @@ python-lsp-server==1.9.0 pytoolconfig==1.2.6 pytz==2023.3.post1 pyyaml==6.0.1 -pyzmq==25.1.1 +pyzmq==25.1.2 qrules==0.9.8 qtconsole==5.5.1 qtpy==2.4.1 -referencing==0.31.1 +referencing==0.32.0 requests==2.31.0 requests-oauthlib==1.3.1 rfc3339-validator==0.1.4 @@ -185,7 +185,7 @@ rfc3986-validator==0.1.1 rope==1.11.0 rpds-py==0.13.2 rsa==4.9 -ruff==0.1.6 +ruff==0.1.7 scipy==1.11.4 send2trash==1.8.2 six==1.16.0 @@ -194,6 +194,7 @@ sniffio==1.3.0 snowballstemmer==2.2.0 soupsieve==2.5 sphinx==6.2.1 +sphinx-api-relink==0.0.6 sphinx-autobuild==2021.3.14 sphinx-book-theme==1.0.1 sphinx-codeautolink==0.15.0 @@ -227,12 +228,9 @@ tornado==6.4 tox==4.11.4 tqdm==4.66.1 traitlets==5.14.0 -types-docutils==0.20.0.3 -types-pkg-resources==0.1.3 types-python-dateutil==2.8.19.14 types-pyyaml==6.0.12.12 types-requests==2.31.0.10 -types-setuptools==69.0.0.0 typing-extensions==4.8.0 tzdata==2023.3 ujson==5.8.0 @@ -242,7 +240,7 @@ virtualenv==20.25.0 wcwidth==0.2.12 webcolors==1.13 webencodings==0.5.1 -websocket-client==1.6.4 +websocket-client==1.7.0 werkzeug==3.0.1 wheel==0.42.0 widgetsnbextension==4.0.9 diff --git a/.constraints/py3.11.txt b/.constraints/py3.11.txt index 3a4ecb82..925935f9 100644 --- a/.constraints/py3.11.txt +++ b/.constraints/py3.11.txt @@ -51,19 +51,19 @@ fqdn==1.5.1 gast==0.5.4 gitdb==4.0.11 gitpython==3.1.40 -google-auth==2.24.0 +google-auth==2.25.2 google-auth-oauthlib==1.1.0 google-pasta==0.2.0 graphviz==0.20.1 -greenlet==3.0.1 -grpcio==1.59.3 +greenlet==3.0.2 +grpcio==1.60.0 h5py==3.10.0 hepunits==2.3.2 -identify==2.5.32 +identify==2.5.33 idna==3.6 imagesize==1.4.1 iminuit==2.24.0 -importlib-metadata==6.9.0 +importlib-metadata==7.0.0 iniconfig==2.0.0 ipykernel==6.27.1 ipympl==0.9.3 @@ -72,8 +72,8 @@ ipython-genutils==0.2.0 ipywidgets==8.1.1 isoduration==20.11.0 isort==5.12.0 -jax==0.4.20 -jaxlib==0.4.20 +jax==0.4.21 +jaxlib==0.4.21 jedi==0.19.1 jinja2==3.1.2 json5==0.9.14 @@ -87,7 +87,7 @@ jupyter-console==6.6.3 jupyter-core==5.5.0 jupyter-events==0.9.0 jupyter-lsp==2.2.1 -jupyter-server==2.11.1 +jupyter-server==2.12.1 jupyter-server-mathjax==0.2.6 jupyter-server-terminals==0.4.4 jupyterlab==4.0.9 @@ -119,7 +119,7 @@ mypy-extensions==1.0.0 myst-nb==1.0.0 myst-parser==2.0.0 nbclient==0.6.8 -nbconvert==7.11.0 +nbconvert==7.12.0 nbdime==4.0.1 nbformat==5.9.2 nbmake==1.4.6 @@ -133,7 +133,7 @@ oauthlib==3.2.2 opt-einsum==3.3.0 overrides==7.4.0 packaging==23.2 -pandas==2.1.3 +pandas==2.1.4 pandocfilters==1.5.0 parso==0.8.3 particle==0.23.1 @@ -141,7 +141,7 @@ pathspec==0.11.2 pexpect==4.9.0 phasespace==1.9.0 pillow==10.1.0 -platformdirs==4.0.0 +platformdirs==4.1.0 pluggy==1.3.0 pre-commit==3.5.0 prometheus-client==0.19.0 @@ -172,11 +172,11 @@ python-lsp-server==1.9.0 pytoolconfig==1.2.6 pytz==2023.3.post1 pyyaml==6.0.1 -pyzmq==25.1.1 +pyzmq==25.1.2 qrules==0.9.8 qtconsole==5.5.1 qtpy==2.4.1 -referencing==0.31.1 +referencing==0.32.0 requests==2.31.0 requests-oauthlib==1.3.1 rfc3339-validator==0.1.4 @@ -184,7 +184,7 @@ rfc3986-validator==0.1.1 rope==1.11.0 rpds-py==0.13.2 rsa==4.9 -ruff==0.1.6 +ruff==0.1.7 scipy==1.11.4 send2trash==1.8.2 six==1.16.0 @@ -193,6 +193,7 @@ sniffio==1.3.0 snowballstemmer==2.2.0 soupsieve==2.5 sphinx==6.2.1 +sphinx-api-relink==0.0.6 sphinx-autobuild==2021.3.14 sphinx-book-theme==1.0.1 sphinx-codeautolink==0.15.0 @@ -225,12 +226,9 @@ tornado==6.4 tox==4.11.4 tqdm==4.66.1 traitlets==5.14.0 -types-docutils==0.20.0.3 -types-pkg-resources==0.1.3 types-python-dateutil==2.8.19.14 types-pyyaml==6.0.12.12 types-requests==2.31.0.10 -types-setuptools==69.0.0.0 typing-extensions==4.8.0 tzdata==2023.3 ujson==5.8.0 @@ -240,7 +238,7 @@ virtualenv==20.25.0 wcwidth==0.2.12 webcolors==1.13 webencodings==0.5.1 -websocket-client==1.6.4 +websocket-client==1.7.0 werkzeug==3.0.1 wheel==0.42.0 widgetsnbextension==4.0.9 diff --git a/.constraints/py3.8.txt b/.constraints/py3.8.txt index 68ac224b..e61ea915 100644 --- a/.constraints/py3.8.txt +++ b/.constraints/py3.8.txt @@ -53,19 +53,19 @@ fqdn==1.5.1 gast==0.4.0 gitdb==4.0.11 gitpython==3.1.40 -google-auth==2.24.0 +google-auth==2.25.2 google-auth-oauthlib==1.0.0 google-pasta==0.2.0 graphviz==0.20.1 -greenlet==3.0.1 -grpcio==1.59.3 +greenlet==3.0.2 +grpcio==1.60.0 h5py==3.10.0 hepunits==2.3.2 -identify==2.5.32 +identify==2.5.33 idna==3.6 imagesize==1.4.1 iminuit==2.24.0 -importlib-metadata==6.9.0 +importlib-metadata==7.0.0 importlib-resources==6.1.1 iniconfig==2.0.0 ipykernel==6.27.1 @@ -90,7 +90,7 @@ jupyter-console==6.6.3 jupyter-core==5.5.0 jupyter-events==0.9.0 jupyter-lsp==2.2.1 -jupyter-server==2.11.1 +jupyter-server==2.12.1 jupyter-server-mathjax==0.2.6 jupyter-server-terminals==0.4.4 jupyterlab==4.0.9 @@ -122,7 +122,7 @@ mypy-extensions==1.0.0 myst-nb==0.17.2 myst-parser==0.18.1 nbclient==0.6.8 -nbconvert==7.11.0 +nbconvert==7.12.0 nbdime==4.0.1 nbformat==5.9.2 nbmake==1.4.6 @@ -146,7 +146,7 @@ phasespace==1.9.0 pickleshare==0.7.5 pillow==10.1.0 pkgutil-resolve-name==1.3.10 -platformdirs==4.0.0 +platformdirs==4.1.0 pluggy==1.3.0 pre-commit==3.5.0 prometheus-client==0.19.0 @@ -177,11 +177,11 @@ python-lsp-server==1.9.0 pytoolconfig==1.2.6 pytz==2023.3.post1 pyyaml==6.0.1 -pyzmq==25.1.1 +pyzmq==25.1.2 qrules==0.9.8 qtconsole==5.5.1 qtpy==2.4.1 -referencing==0.31.1 +referencing==0.32.0 requests==2.31.0 requests-oauthlib==1.3.1 rfc3339-validator==0.1.4 @@ -189,7 +189,7 @@ rfc3986-validator==0.1.1 rope==1.11.0 rpds-py==0.13.2 rsa==4.9 -ruff==0.1.6 +ruff==0.1.7 scipy==1.10.1 send2trash==1.8.2 six==1.16.0 @@ -198,6 +198,7 @@ sniffio==1.3.0 snowballstemmer==2.2.0 soupsieve==2.5 sphinx==5.3.0 +sphinx-api-relink==0.0.6 sphinx-autobuild==2021.3.14 sphinx-book-theme==1.0.1 sphinx-codeautolink==0.15.0 @@ -231,12 +232,9 @@ tornado==6.4 tox==4.11.4 tqdm==4.66.1 traitlets==5.14.0 -types-docutils==0.20.0.3 -types-pkg-resources==0.1.3 types-python-dateutil==2.8.19.14 types-pyyaml==6.0.12.12 types-requests==2.31.0.10 -types-setuptools==69.0.0.0 typing-extensions==4.5.0 tzdata==2023.3 ujson==5.8.0 @@ -246,7 +244,7 @@ virtualenv==20.25.0 wcwidth==0.2.12 webcolors==1.13 webencodings==0.5.1 -websocket-client==1.6.4 +websocket-client==1.7.0 werkzeug==3.0.1 wheel==0.42.0 widgetsnbextension==4.0.9 diff --git a/.constraints/py3.9.txt b/.constraints/py3.9.txt index aff3e03f..748a2990 100644 --- a/.constraints/py3.9.txt +++ b/.constraints/py3.9.txt @@ -52,19 +52,19 @@ fqdn==1.5.1 gast==0.5.4 gitdb==4.0.11 gitpython==3.1.40 -google-auth==2.24.0 +google-auth==2.25.2 google-auth-oauthlib==1.1.0 google-pasta==0.2.0 graphviz==0.20.1 -greenlet==3.0.1 -grpcio==1.59.3 +greenlet==3.0.2 +grpcio==1.60.0 h5py==3.10.0 hepunits==2.3.2 -identify==2.5.32 +identify==2.5.33 idna==3.6 imagesize==1.4.1 iminuit==2.24.0 -importlib-metadata==6.9.0 +importlib-metadata==7.0.0 importlib-resources==6.1.1 iniconfig==2.0.0 ipykernel==6.27.1 @@ -74,8 +74,8 @@ ipython-genutils==0.2.0 ipywidgets==8.1.1 isoduration==20.11.0 isort==5.12.0 -jax==0.4.20 -jaxlib==0.4.20 +jax==0.4.21 +jaxlib==0.4.21 jedi==0.19.1 jinja2==3.1.2 json5==0.9.14 @@ -89,7 +89,7 @@ jupyter-console==6.6.3 jupyter-core==5.5.0 jupyter-events==0.9.0 jupyter-lsp==2.2.1 -jupyter-server==2.11.1 +jupyter-server==2.12.1 jupyter-server-mathjax==0.2.6 jupyter-server-terminals==0.4.4 jupyterlab==4.0.9 @@ -121,7 +121,7 @@ mypy-extensions==1.0.0 myst-nb==1.0.0 myst-parser==2.0.0 nbclient==0.6.8 -nbconvert==7.11.0 +nbconvert==7.12.0 nbdime==4.0.1 nbformat==5.9.2 nbmake==1.4.6 @@ -135,7 +135,7 @@ oauthlib==3.2.2 opt-einsum==3.3.0 overrides==7.4.0 packaging==23.2 -pandas==2.1.3 +pandas==2.1.4 pandocfilters==1.5.0 parso==0.8.3 particle==0.23.1 @@ -143,7 +143,7 @@ pathspec==0.11.2 pexpect==4.9.0 phasespace==1.9.0 pillow==10.1.0 -platformdirs==4.0.0 +platformdirs==4.1.0 pluggy==1.3.0 pre-commit==3.5.0 prometheus-client==0.19.0 @@ -174,11 +174,11 @@ python-lsp-server==1.9.0 pytoolconfig==1.2.6 pytz==2023.3.post1 pyyaml==6.0.1 -pyzmq==25.1.1 +pyzmq==25.1.2 qrules==0.9.8 qtconsole==5.5.1 qtpy==2.4.1 -referencing==0.31.1 +referencing==0.32.0 requests==2.31.0 requests-oauthlib==1.3.1 rfc3339-validator==0.1.4 @@ -186,7 +186,7 @@ rfc3986-validator==0.1.1 rope==1.11.0 rpds-py==0.13.2 rsa==4.9 -ruff==0.1.6 +ruff==0.1.7 scipy==1.11.4 send2trash==1.8.2 six==1.16.0 @@ -195,6 +195,7 @@ sniffio==1.3.0 snowballstemmer==2.2.0 soupsieve==2.5 sphinx==6.2.1 +sphinx-api-relink==0.0.6 sphinx-autobuild==2021.3.14 sphinx-book-theme==1.0.1 sphinx-codeautolink==0.15.0 @@ -228,12 +229,9 @@ tornado==6.4 tox==4.11.4 tqdm==4.66.1 traitlets==5.14.0 -types-docutils==0.20.0.3 -types-pkg-resources==0.1.3 types-python-dateutil==2.8.19.14 types-pyyaml==6.0.12.12 types-requests==2.31.0.10 -types-setuptools==69.0.0.0 typing-extensions==4.8.0 tzdata==2023.3 ujson==5.8.0 @@ -243,7 +241,7 @@ virtualenv==20.25.0 wcwidth==0.2.12 webcolors==1.13 webencodings==0.5.1 -websocket-client==1.6.4 +websocket-client==1.7.0 werkzeug==3.0.1 wheel==0.42.0 widgetsnbextension==4.0.9 diff --git a/.cspell.json b/.cspell.json index ce12843d..1514d3f6 100644 --- a/.cspell.json +++ b/.cspell.json @@ -20,6 +20,7 @@ "transisions" ], "ignorePaths": [ + "**/*.rst_t", "**/.cspell.json", ".constraints/*.txt", ".editorconfig", diff --git a/.gitignore b/.gitignore index 2b8d0d1a..5dc65be5 100644 --- a/.gitignore +++ b/.gitignore @@ -25,11 +25,13 @@ version.py .coverage .coverage.* .ipynb_checkpoints/ +.jupyter_ystore.db .mypy*/ .pytest_cache/ .virtual_documents/ __pycache__/ htmlcov/ +oryx-build-commands.txt prof/ # Virtual environments diff --git a/.gitpod.yml b/.gitpod.yml index d981b21f..7945c72f 100644 --- a/.gitpod.yml +++ b/.gitpod.yml @@ -1,4 +1,5 @@ tasks: + - init: pyenv local 3.8 - init: pip install -c .constraints/py3.8.txt -e .[dev] github: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 16802806..63a6fddc 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -14,6 +14,25 @@ repos: - id: check-hooks-apply - id: check-useless-excludes + - repo: https://github.com/ComPWA/repo-maintenance + rev: 0.1.9 + hooks: + - id: check-dev-files + args: + - --ci-test-extras=all + - --doc-apt-packages=graphviz + - --no-prettierrc + - --pin-requirements=monthly + - --repo-name=tensorwaves + - --repo-title=TensorWaves + - id: colab-toc-visible + - id: fix-nbformat-version + - id: set-nb-cells + args: + - --add-install-cell + - --additional-packages=IPython + - --extras-require=doc,jax,pwa,viz + - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.5.0 hooks: @@ -41,25 +60,6 @@ repos: )$ - id: trailing-whitespace - - repo: https://github.com/ComPWA/repo-maintenance - rev: 0.1.6 - hooks: - - id: check-dev-files - args: - - --ci-test-extras=all - - --doc-apt-packages=graphviz - - --no-prettierrc - - --pin-requirements=monthly - - --repo-name=tensorwaves - - --repo-title=TensorWaves - - id: colab-toc-visible - - id: fix-nbformat-version - - id: set-nb-cells - args: - - --add-install-cell - - --additional-packages=IPython - - --extras-require=doc,jax,pwa,viz - - repo: https://github.com/psf/black-pre-commit-mirror rev: 23.11.0 hooks: @@ -74,7 +74,7 @@ repos: - id: blacken-docs - repo: https://github.com/python-jsonschema/check-jsonschema - rev: 0.27.2 + rev: 0.27.3 hooks: - id: check-jsonschema name: Check CITATION.cff @@ -87,7 +87,7 @@ repos: pass_filenames: false - repo: https://github.com/streetsidesoftware/cspell-cli - rev: v8.0.0 + rev: v8.1.1 hooks: - id: cspell @@ -138,17 +138,17 @@ repos: metadata.vscode - repo: https://github.com/pre-commit/mirrors-prettier - rev: v4.0.0-alpha.3 + rev: v4.0.0-alpha.3-1 hooks: - id: prettier - repo: https://github.com/ComPWA/mirrors-pyright - rev: v1.1.338 + rev: v1.1.339 hooks: - id: pyright - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.1.6 + rev: v0.1.7 hooks: - id: ruff args: [--fix] diff --git a/.readthedocs.yml b/.readthedocs.yml index 6c62be1f..f34ae963 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -9,11 +9,11 @@ formats: - htmlzip build: - os: ubuntu-20.04 + os: ubuntu-22.04 tools: python: "3.8" apt_packages: - graphviz jobs: post_install: - - pip install -e .[doc] -c .constraints/py3.8.txt + - pip install -c .constraints/py3.8.txt -e .[doc] diff --git a/.vscode/settings.json b/.vscode/settings.json index 9f0ae66e..6581b8fb 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -17,7 +17,7 @@ }, "[python]": { "editor.codeActionsOnSave": { - "source.organizeImports": true + "source.organizeImports": "explicit" }, "editor.defaultFormatter": "ms-python.black-formatter", "editor.rulers": [88] diff --git a/docs/_relink_references.py b/docs/_relink_references.py deleted file mode 100644 index 876b02a3..00000000 --- a/docs/_relink_references.py +++ /dev/null @@ -1,106 +0,0 @@ -"""Abbreviated the annotations generated by sphinx-autodoc. - -It's not necessary to generate the full path of type hints, because they are rendered as -clickable links. - -See also https://github.com/sphinx-doc/sphinx/issues/5868. -""" - -# pyright: reportMissingImports=false -from __future__ import annotations - -from typing import TYPE_CHECKING - -import sphinx.domains.python -from docutils import nodes -from sphinx.addnodes import pending_xref - -if TYPE_CHECKING: - from sphinx.environment import BuildEnvironment - -__TARGET_SUBSTITUTIONS = { - "DataSample": "tensorwaves.interface.DataSample", - "HelicityAdapter": "ampform.kinematics.HelicityAdapter", - "ParameterValue": "tensorwaves.interface.ParameterValue", - "Path": "pathlib.Path", - "a set-like object providing a view on D's items": "typing.ItemsView", - "a set-like object providing a view on D's keys": "typing.KeysView", - "an object providing a view on D's values": "typing.ValuesView", - "np.ndarray": "numpy.ndarray", - "sp.Expr": "sympy.core.expr.Expr", - "sp.Symbol": "sympy.core.symbol.Symbol", -} -__REF_TYPE_SUBSTITUTIONS = { - "None": "obj", - "tensorwaves.interface.DataSample": "obj", - "tensorwaves.interface.InputType": "obj", - "tensorwaves.interface.OutputType": "obj", - "tensorwaves.interface.ParameterValue": "obj", -} - - -try: # Sphinx >=4.4.0 - # https://github.com/sphinx-doc/sphinx/blob/v4.4.0/sphinx/domains/python.py#L110-L133 - from sphinx.addnodes import pending_xref_condition - from sphinx.domains.python import parse_reftarget - - def _new_type_to_xref( - target: str, - env: BuildEnvironment | None = None, - suppress_prefix: bool = False, - ) -> pending_xref: - reftype, target, title, refspecific = parse_reftarget(target, suppress_prefix) - target = __TARGET_SUBSTITUTIONS.get(target, target) - reftype = __REF_TYPE_SUBSTITUTIONS.get(target, reftype) - assert env is not None - return pending_xref( - "", - *__create_nodes(env, title), - refdomain="py", - reftype=reftype, - reftarget=target, - refspecific=refspecific, - **__get_env_kwargs(env), - ) - -except ImportError: # Sphinx <4.4.0 - # https://github.com/sphinx-doc/sphinx/blob/v4.3.2/sphinx/domains/python.py#L83-L107 - def _new_type_to_xref( - target: str, - env: BuildEnvironment | None = None, - suppress_prefix: bool = False, - ) -> pending_xref: - target = __TARGET_SUBSTITUTIONS.get(target, target) - reftype = __REF_TYPE_SUBSTITUTIONS.get(target, "class") - assert env is not None - return pending_xref( - "", - *__create_nodes(env, target), - refdomain="py", - reftype=reftype, - reftarget=target, - **__get_env_kwargs(env), - ) - - -def __get_env_kwargs(env: BuildEnvironment) -> dict: - if env: - return { - "py:module": env.ref_context.get("py:module"), - "py:class": env.ref_context.get("py:class"), - } - return {} - - -def __create_nodes(env: BuildEnvironment, title: str) -> list[nodes.Node]: - short_name = title.split(".")[-1] - if env.config.python_use_unqualified_type_names: - return [ - pending_xref_condition("", short_name, condition="resolved"), - pending_xref_condition("", title, condition="*"), - ] - return [nodes.Text(short_name)] - - -def relink_references() -> None: - sphinx.domains.python.type_to_xref = _new_type_to_xref diff --git a/docs/conf.py b/docs/conf.py index e27f7d58..58460b72 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,104 +4,112 @@ documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html """ -import contextlib +from __future__ import annotations + import os -import re -import shutil import subprocess -import sys import requests -from importlib_metadata import PackageNotFoundError -from importlib_metadata import version as get_package_version - -# -- Project information ----------------------------------------------------- -project = "TensorWaves" -PACKAGE = "tensorwaves" -REPO_NAME = "tensorwaves" -copyright = "2020, ComPWA" # noqa: A001 -author = "Common Partial Wave Analysis" - +from sphinx_api_relink.helpers import ( + get_branch_name, + get_execution_mode, + get_package_version, + pin, + pin_minor, + set_intersphinx_version_remapping, +) -# https://docs.readthedocs.io/en/stable/builds.html -def get_branch_name() -> str: - branch_name = os.environ.get("READTHEDOCS_VERSION", "stable") - if branch_name == "latest": - return "main" - if re.match(r"^\d+$", branch_name): # PR preview - return "stable" - return branch_name +def create_tensorflow_inventory() -> None: + if os.path.exists("tensorflow.inv"): + return + subprocess.check_call( + ("sphobjinv", "convert", "-o", "zlib", "tensorflow.txt"), # noqa: S603 + ) -BRANCH = get_branch_name() -try: - __VERSION = get_package_version(PACKAGE) - version = ".".join(__VERSION.split(".")[:3]) -except PackageNotFoundError: - pass +def get_scipy_url() -> str: + url = f"https://docs.scipy.org/doc/scipy-{pin('scipy')}/" + r = requests.get(url) + if r.status_code != 200: # noqa: PLR2004 + return "https://docs.scipy.org/doc/scipy" + return url -# -- Fetch logo -------------------------------------------------------------- -def fetch_logo(url: str, output_path: str) -> None: - if os.path.exists(output_path): - return - online_content = requests.get(url, allow_redirects=True) - with open(output_path, "wb") as stream: - stream.write(online_content.content) +def get_tensorflow_url() -> str: + url = f"https://www.tensorflow.org/versions/r{pin_minor('tensorflow')}/api_docs/python" + r = requests.get(url + "/tf") + if r.status_code != 200: # noqa: PLR2004 + url = "https://www.tensorflow.org/api_docs/python" + return url -LOGO_PATH = "_static/logo.svg" -with contextlib.suppress(requests.exceptions.ConnectionError): - fetch_logo( - url="https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg", - output_path=LOGO_PATH, - ) -if os.path.exists(LOGO_PATH): - html_logo = LOGO_PATH +create_tensorflow_inventory() +set_intersphinx_version_remapping({ + "matplotlib": {"3.5.1": "3.5.0"}, + "scipy": {"1.7.3": "1.7.1"}, +}) -# -- Generate API ------------------------------------------------------------ -sys.path.insert(0, os.path.abspath(".")) -from _relink_references import relink_references +BRANCH = get_branch_name() +ORGANIZATION = "ComPWA" +PACKAGE = "tensorwaves" +REPO_NAME = "tensorwaves" +REPO_TITLE = "TensorWaves" -relink_references() -shutil.rmtree("api", ignore_errors=True) -subprocess.call( - " ".join([ - "sphinx-apidoc", - f"../src/{PACKAGE}/", - f"../src/{PACKAGE}/version.py", - "-o api/", - "--force", - "--no-toc", - "--templatedir _templates", - "--separate", - ]), - shell=True, # noqa: S602 +BINDER_LINK = ( + f"https://mybinder.org/v2/gh/ComPWA/{REPO_NAME}/{BRANCH}?filepath=docs/usage" ) -# -- Convert sphinx object inventory ----------------------------------------- -if not os.path.exists("tensorflow.inv"): - subprocess.call( - "sphobjinv convert -o zlib tensorflow.txt", # noqa: S607 - shell=True, # noqa: S602 - ) - - -# -- General configuration --------------------------------------------------- -master_doc = "index.md" -source_suffix = { - ".ipynb": "myst-nb", - ".md": "myst-nb", - ".rst": "restructuredtext", +add_module_names = False +api_github_repo = f"{ORGANIZATION}/{REPO_NAME}" +api_target_substitutions: dict[str, str | tuple[str, str]] = { + "DataSample": "tensorwaves.interface.DataSample", + "ParameterValue": "tensorwaves.interface.ParameterValue", + "Path": "pathlib.Path", + "np.ndarray": "numpy.ndarray", + "sp.Expr": "sympy.core.expr.Expr", + "sp.Symbol": "sympy.core.symbol.Symbol", } - -# The master toctree document. -master_doc = "index" -modindex_common_prefix = [ - f"{PACKAGE}.", +api_target_types: dict[str, str | tuple[str, str]] = { + "tensorwaves.interface.DataSample": "obj", + "tensorwaves.interface.InputType": "obj", + "tensorwaves.interface.OutputType": "obj", + "tensorwaves.interface.ParameterValue": "obj", +} +author = "Common Partial Wave Analysis" +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, +} +autodoc_member_order = "bysource" +autodoc_type_aliases = { + "DataSample": "tensorwaves.interface.DataSample", + "InputType": "tensorwaves.interface.InputType", + "OutputType": "tensorwaves.interface.OutputType", + "ParameterValue": "tensorwaves.interface.ParameterValue", +} +autodoc_typehints_format = "short" +autosectionlabel_prefix_document = True +codeautolink_concat_default = True +comments_config = { + "hypothesis": True, + "utterances": { + "repo": f"ComPWA/{REPO_NAME}", + "issue-term": "pathname", + "label": "📝 Docs", + }, +} +copybutton_prompt_is_regexp = True +copybutton_prompt_text = r">>> |\.\.\. " # doctest +copyright = f"2020, {ORGANIZATION}" +default_role = "py:obj" +exclude_patterns = [ + "**.ipynb_checkpoints", + "*build", + "adr*", + "tests", ] - extensions = [ "myst_nb", "sphinx.ext.autodoc", @@ -110,7 +118,7 @@ def fetch_logo(url: str, output_path: str) -> None: "sphinx.ext.intersphinx", "sphinx.ext.mathjax", "sphinx.ext.napoleon", - "sphinx.ext.viewcode", + "sphinx_api_relink", "sphinx_codeautolink", "sphinx_comments", "sphinx_copybutton", @@ -118,37 +126,14 @@ def fetch_logo(url: str, output_path: str) -> None: "sphinx_thebe", "sphinx_togglebutton", ] -exclude_patterns = [ - "**.ipynb_checkpoints", - "*build", - "adr*", - "tests", -] - -# General sphinx settings -add_module_names = False -autodoc_default_options = { - "members": True, - "undoc-members": True, - "show-inheritance": True, -} -autodoc_member_order = "bysource" -autodoc_type_aliases = { - "DataSample": "tensorwaves.interface.DataSample", - "InputType": "tensorwaves.interface.InputType", - "OutputType": "tensorwaves.interface.OutputType", - "ParameterValue": "tensorwaves.interface.ParameterValue", -} -autodoc_typehints_format = "short" -codeautolink_concat_default = True -AUTODOC_INSERT_SIGNATURE_LINEBREAKS = False +generate_apidoc_package_path = f"../src/{PACKAGE}" graphviz_output_format = "svg" html_copy_source = True # needed for download notebook button -html_css_files = [] -if AUTODOC_INSERT_SIGNATURE_LINEBREAKS: - html_css_files.append("linebreaks-api.css") html_favicon = "_static/favicon.ico" html_last_updated_fmt = "%-d %B %Y" +html_logo = ( + "https://raw.githubusercontent.com/ComPWA/ComPWA/04e5199/doc/images/logo.svg" +) html_show_copyright = False html_show_sourcelink = False html_show_sphinx = False @@ -194,8 +179,8 @@ def fetch_logo(url: str, output_path: str) -> None: "type": "url", }, ], - "logo": {"text": project}, - "repository_url": f"https://github.com/ComPWA/{REPO_NAME}", + "logo": {"text": REPO_TITLE}, + "repository_url": f"https://github.com/{ORGANIZATION}/{REPO_NAME}", "repository_branch": BRANCH, "path_to_docs": "docs", "use_download_button": True, @@ -213,140 +198,32 @@ def fetch_logo(url: str, output_path: str) -> None: "show_navbar_depth": 2, "show_toc_level": 2, } -html_title = project -pygments_style = "sphinx" -todo_include_todos = False -viewcode_follow_imported_members = True - -# Cross-referencing configuration -default_role = "py:obj" -primary_domain = "py" -nitpicky = True # warn if cross-references are missing -nitpick_ignore = [ - ("py:class", "tensorflow.keras.losses.Loss"), - ("py:class", "tensorflow.python.keras.losses.Loss"), - ("py:obj", "Loss"), -] - - -# Intersphinx settings -version_remapping = { - "matplotlib": {"3.5.1": "3.5.0"}, - "scipy": {"1.7.3": "1.7.1"}, -} - - -def get_version(package_name: str) -> str: - python_version = f"{sys.version_info.major}.{sys.version_info.minor}" - constraints_path = f"../.constraints/py{python_version}.txt" - with open(constraints_path) as stream: - constraints = stream.read() - for line in constraints.split("\n"): - line = line.split("#")[0] # remove comments - line = line.strip() - if not line.startswith(package_name): - continue - if not line: - continue - line_segments = tuple(line.split("==")) - if len(line_segments) != 2: # noqa: PLR2004 - continue - _, installed_version, *_ = line_segments - installed_version = installed_version.strip() - remapped_versions = version_remapping.get(package_name) - if remapped_versions is not None: - existing_version = remapped_versions.get(installed_version) - if existing_version is not None: - return existing_version - return installed_version - return "stable" - - -def get_minor_version(package_name: str) -> str: - installed_version = get_version(package_name) - if installed_version == "stable": - return installed_version - matches = re.match(r"^([0-9]+\.[0-9]+).*$", installed_version) - if matches is None: - msg = f"Could not find documentation for {package_name} v{installed_version}" - raise ValueError(msg) - return matches[1] - - -def get_scipy_url() -> str: - url = f"https://docs.scipy.org/doc/scipy-{get_version('scipy')}/" - r = requests.get(url) - if r.status_code != 200: # noqa: PLR2004 - return "https://docs.scipy.org/doc/scipy" - return url - - -def get_tensorflow_url() -> str: - url = f"https://www.tensorflow.org/versions/r{get_minor_version('tensorflow')}/api_docs/python" - r = requests.get(url + "/tf") - if r.status_code != 200: # noqa: PLR2004 - url = "https://www.tensorflow.org/api_docs/python" - return url - - +html_title = REPO_TITLE intersphinx_mapping = { - "ampform": ( - f"https://ampform.readthedocs.io/en/{get_version('ampform')}", - None, - ), + "ampform": (f"https://ampform.readthedocs.io/en/{pin('ampform')}", None), "compwa-org": ("https://compwa-org.readthedocs.io", None), "graphviz": ("https://graphviz.readthedocs.io/en/stable", None), "iminuit": ("https://iminuit.readthedocs.io/en/stable", None), "jax": ("https://jax.readthedocs.io/en/latest", None), - "matplotlib": ( - f"https://matplotlib.org/{get_version('matplotlib')}", - None, - ), - "numpy": (f"https://numpy.org/doc/{get_minor_version('numpy')}", None), - "pandas": ( - f"https://pandas.pydata.org/pandas-docs/version/{get_version('pandas')}", - None, - ), + "matplotlib": (f"https://matplotlib.org/{pin('matplotlib')}", None), + "numpy": (f"https://numpy.org/doc/{pin_minor('numpy')}", None), + "pandas": (f"https://pandas.pydata.org/pandas-docs/version/{pin('pandas')}", None), "pwa": ("https://pwa.readthedocs.io", None), "python": ("https://docs.python.org/3", None), - "qrules": ( - f"https://qrules.readthedocs.io/en/{get_version('qrules')}", - None, - ), + "qrules": (f"https://qrules.readthedocs.io/en/{pin('qrules')}", None), "scipy": (get_scipy_url(), None), "sympy": ("https://docs.sympy.org/latest", None), "tensorflow": (get_tensorflow_url(), "tensorflow.inv"), } - -# Settings for autosectionlabel -autosectionlabel_prefix_document = True - -# Settings for copybutton -copybutton_prompt_is_regexp = True -copybutton_prompt_text = r">>> |\.\.\. " # doctest - -# Settings for linkcheck -linkcheck_anchors = False -if os.environ.get("CI", False): - linkcheck_anchors = True - linkcheck_anchors_ignore = [ - r"pip\-installation\-gpu\-cuda", - ] +linkcheck_anchors = bool(os.environ.get("CI", False)) +linkcheck_anchors_ignore = [ + r"pip\-installation\-gpu\-cuda", +] linkcheck_ignore = [ "https://unix.stackexchange.com/a/129144", ] - -# Settings for myst_nb -nb_execution_show_tb = True -nb_execution_timeout = -1 -nb_output_stderr = "remove" - -nb_execution_mode = "off" -if "EXECUTE_NB" in os.environ: - print("\033[93;1mWill run Jupyter notebooks!\033[0m") - nb_execution_mode = "cache" - -# Settings for myst-parser +master_doc = "index" +modindex_common_prefix = [f"{PACKAGE}."] myst_enable_extensions = [ "amsmath", "colon_fence", @@ -355,9 +232,6 @@ def get_tensorflow_url() -> str: "substitution", ] myst_heading_anchors = 4 -BINDER_LINK = ( - f"https://mybinder.org/v2/gh/ComPWA/{REPO_NAME}/{BRANCH}?filepath=docs/usage" -) myst_substitutions = { "branch": BRANCH, "run_interactive": f""" @@ -369,19 +243,27 @@ def get_tensorflow_url() -> str: """, } myst_update_mathjax = False - -# Settings for sphinx_comments -comments_config = { - "hypothesis": True, - "utterances": { - "repo": f"ComPWA/{REPO_NAME}", - "issue-term": "pathname", - "label": "📝 Docs", - }, +nb_execution_mode = get_execution_mode() +nb_execution_show_tb = True +nb_execution_timeout = -1 +nb_output_stderr = "remove" +nitpick_ignore = [ + ("py:class", "tensorflow.keras.losses.Loss"), + ("py:class", "tensorflow.python.keras.losses.Loss"), + ("py:obj", "Loss"), +] +nitpicky = True +primary_domain = "py" +project = REPO_TITLE +pygments_style = "sphinx" +release = get_package_version("tensorwaves") +source_suffix = { + ".ipynb": "myst-nb", + ".md": "myst-nb", + ".rst": "restructuredtext", } - -# Settings for Thebe cell output thebe_config = { "repository_url": html_theme_options["repository_url"], "repository_branch": html_theme_options["repository_branch"], } +version = get_package_version("tensorwaves") diff --git a/environment.yml b/environment.yml index a4c8ea49..65cec60b 100644 --- a/environment.yml +++ b/environment.yml @@ -6,9 +6,7 @@ dependencies: - pip>=19 - graphviz # for binder - pip: - - | - -c .constraints/py3.8.txt - -e .[dev] + - -c .constraints/py3.8.txt -e .[dev] variables: PRETTIER_LEGACY_CLI: "1" PYTHONHASHSEED: 0 diff --git a/pyproject.toml b/pyproject.toml index 3fc26d06..dc16fc80 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -74,6 +74,7 @@ doc = [ "myst-nb >=0.14", # nb_ configuration prefixes "nbclient >=0.5.5", # https://github.com/executablebooks/jupyter-book/issues/833 "pandas", + "sphinx-api-relink >=0.0.4", "sphinx-book-theme", "sphinx-codeautolink[ipython]", "sphinx-comments", @@ -108,14 +109,12 @@ lint = [ ] mypy = [ "mypy >=0.570", # attrs support + "sphinx-api-relink >=0.0.4", "tensorwaves[jax]", "tensorwaves[pwa]", "tensorwaves[test-types]", "types-PyYAML", - "types-docutils", - "types-pkg-resources", "types-requests", - "types-setuptools", ] numba = [ "numba", @@ -156,6 +155,7 @@ test-types = [ "pytest-mock >=3.3.0", ] tf = [ + "tensorflow !=2.15.0.post1", # https://github.com/ComPWA/tensorwaves/actions/runs/7147814088/job/19467965144?pr=509 "tensorflow >=2.4", # tensorflow.experimental.numpy ] viz = [ @@ -400,7 +400,7 @@ task-tags = ["cspell"] "PLW0603", "S101", "S301", - "T201", + "T20", "TCH00", ] "*docs/usage/faster-lambdify.ipynb" = [ @@ -420,7 +420,7 @@ task-tags = ["cspell"] "S113", "T201", ] -"docs/conf.py" = ["PLW2901"] +"docs/conf.py" = ["A001"] "setup.py" = ["D100"] "tests/*" = [ "D", @@ -429,6 +429,7 @@ task-tags = ["cspell"] "PLR0913", "PLR2004", "S101", + "T20", ] [tool.ruff.pydocstyle] diff --git a/tests/data/test_phasespace.py b/tests/data/test_phasespace.py index c4c67f49..15739101 100644 --- a/tests/data/test_phasespace.py +++ b/tests/data/test_phasespace.py @@ -152,8 +152,8 @@ def test_generate_deterministic(self, pdg: "ParticleCollection"): assert list(phsp_momenta) == ["weights", "p0", "p1", "p2"] weights = phsp_momenta.get("weights", []) # type: ignore[var-annotated] del phsp_momenta["weights"] - print("Expected values, get by running pytest with the -s flag") # noqa: T201 - pprint({ # noqa: T203 + print("Expected values, get by running pytest with the -s flag") + pprint({ i: np.round(four_momenta, decimals=10).tolist() for i, four_momenta in phsp_momenta.items() })