chore: build documentation with make (#433)

* ci: add jcache tox job
* ci: define dependabot for GitHub Actions
* ci: pass GITHUB_REPO environment variable
* ci: pass GITHUB_TOKEN environment variable
* ci: run MyST-NB with cache
  https://myst-nb.readthedocs.io/en/v0.15.0/computation/execute.html#notebook-execution-modes
* fix: update link to scipy inventory
* style: use 2 spaces indent size in ini files

.cspell.json

@@ -44,7 +44,6 @@
         "docs/adr/*/*",
         "docs/conf.py",
         "labels.toml",
-        "Makefile",
         "pyproject.toml",
         "pyrightconfig.json",
         "pytest.ini",

.editorconfig

@@ -2,22 +2,20 @@ root = true
 
 [*]
 end_of_line = lf
+indent_size = 2
 indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[Makefile]
-indent_style = tab
+[*.ipynb]
+indent_size = 1
 
-[*.{py,toml}]
+[*.{py,pyi,toml}]
 indent_size = 4
 
-[*.{json,yaml,yml}]
-indent_size = 2
-
-[*.{rst,inc}]
-indent_size = 2
-
 # when adding words through vscode, this is the resulting output format
 [.cspell.json]
 indent_size = 4
+
+[setup.cfg]
+indent_size = 4

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    assignees:
+      - redeboer
+    labels:
+      - 🖱️ DX
+    schedule:
+      interval: monthly

.github/workflows/benchmark.yml

@@ -14,7 +14,7 @@ jobs:
     name: Performance regression
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: actions/setup-python@v2
         with:
           python-version: 3.9

.github/workflows/cd.yml

@@ -36,7 +36,7 @@ jobs:
     needs: push
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python
         uses: actions/setup-python@v2
         with:

.github/workflows/ci-docs.yml

@@ -18,22 +18,22 @@ jobs:
     name: Build documentation and run notebooks
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
           python-version: "3.8"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c .constraints/py3.8.txt .[doc]
+          pip install -c .constraints/py3.8.txt .[doc] tox
           sudo apt-get -y install graphviz pandoc
       - name: Build documentation and run notebooks
-        working-directory: docs
         env:
-          EXECUTE_NB: YES
+          GITHUB_REPO: ${{ github.event.pull_request.head.repo.full_name }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: make html
+        run: tox -e docnb
+        # cspell:ignore docnb
       - name: Print error logs with color
         if: ${{ failure() }}
         # cspell:ignore printf

.github/workflows/ci-style.yml

@@ -18,7 +18,7 @@ jobs:
     name: Style checks
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:

.github/workflows/ci-tests.yml

@@ -84,7 +84,7 @@ jobs:
           - os: macos-11
             python-version: "3.7"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:
@@ -118,7 +118,7 @@ jobs:
     name: Unit tests (JAX only)
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python 3.9
         uses: actions/setup-python@v2
         with:
@@ -146,7 +146,7 @@ jobs:
     if: join(github.event.inputs.*)
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:

.github/workflows/linkcheck.yml

@@ -16,23 +16,23 @@ jobs:
     name: Check external links
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
           python-version: "3.8"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c .constraints/py3.8.txt -e .[doc]
+          pip install -c .constraints/py3.8.txt -e .[doc] tox
           sudo apt-get -y install graphviz pandoc
       - name: Check external links
-        working-directory: docs
         env:
-          REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          GITHUB_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           BRANCH=main
           if [[ "$GITHUB_HEAD_REF" != "" ]]; then
             BRANCH=$GITHUB_HEAD_REF
           fi
-          READTHEDOCS_VERSION=$BRANCH make ignore-warnings=1 linkcheck
+          READTHEDOCS_VERSION=$BRANCH tox -e linkcheck

.github/workflows/requirements-cron.yml

@@ -37,7 +37,7 @@ jobs:
           - "3.8"
           - "3.9"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ComPWA/update-pip-constraints@main
         with:
           python-version: ${{ matrix.python-version }}
@@ -48,7 +48,7 @@ jobs:
     if: needs.is-even-week.outputs.is-even-week != 0
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ComPWA/update-pre-commit@main
 
   push:
@@ -58,7 +58,7 @@ jobs:
       - pip-constraints
       - pre-commit
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           token: ${{ secrets.PAT }}
         # GITHUB_TOKEN will not rerun checks after pushing to a PR branch

.github/workflows/requirements-pr.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           fetch-depth: 0
       - name: Determine dependency changes
@@ -40,7 +40,7 @@ jobs:
           - "3.8"
           - "3.9"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ComPWA/update-pip-constraints@main
         with:
           python-version: ${{ matrix.python-version }}
@@ -53,7 +53,7 @@ jobs:
       needs.diff.outputs.diff != ''
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ComPWA/update-pre-commit@main
 
   push:
@@ -67,7 +67,7 @@ jobs:
       - pip-constraints
       - pre-commit
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           token: ${{ secrets.PAT }}
         # GITHUB_TOKEN will not rerun checks after pushing to a PR branch

.pre-commit-config.yaml

@@ -44,7 +44,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/ComPWA/repo-maintenance
-    rev: 0.0.124
+    rev: 0.0.127
     hooks:
       - id: check-dev-files
         args:
@@ -78,7 +78,9 @@ repos:
       - id: editorconfig-checker
         exclude: >
           (?x)^(
-            .*\.py
+            .*\.md|
+            .*\.py|
+            LICENSE
           )$
 
   - repo: https://github.com/pycqa/isort

docs/_templates/module.rst_t

@@ -3,10 +3,10 @@
 
 .. code-block:: python
 
-    import {{ basename }}
+  import {{ basename }}
 
 {% endif -%}
 .. automodule:: {{ qualname }}
 {%- for option in automodule_options %}
-   :{{ option }}:
+  :{{ option }}:
 {%- endfor %}

docs/_templates/package.rst_t

@@ -1,22 +1,22 @@
 {%- macro automodule(modname, options) -%}
 .. automodule:: {{ modname }}
 {%- for option in options %}
-   :{{ option }}:
+  :{{ option }}:
 {%- endfor %}
 {%- endmacro %}
 
 {%- macro toctree(docnames) -%}
 .. toctree::
 {% for docname in docnames %}
-   {{ docname }}
+  {{ docname }}
 {%- endfor %}
 {%- endmacro %}
 
 {{ pkgname.split(".")[-1] | e | heading }}
 
 .. code-block:: python
 
-    import {{ pkgname }}
+  import {{ pkgname }}
 
 {%- if modulefirst and not is_namespace %}
 {{ automodule(pkgname, automodule_options) }}

docs/_templates/toc.rst_t

@@ -1,7 +1,7 @@
 {{ header | heading }}
 
 .. toctree::
-   :maxdepth: {{ maxdepth }}
+  :maxdepth: {{ maxdepth }}
 {% for docname in docnames %}
-   {{ docname }}
+  {{ docname }}
 {%- endfor %}

docs/conf.py

@@ -228,9 +228,7 @@ def get_minor_version(package_name: str) -> str:
     return matches[1]
 
 
-__SCIPY_URL = (
-    f"https://docs.scipy.org/doc/scipy-{get_version('scipy')}/reference/"
-)
+__SCIPY_URL = f"https://docs.scipy.org/doc/scipy-{get_version('scipy')}/"
 r = requests.get(__SCIPY_URL)
 if r.status_code != 200:
     __SCIPY_URL = "https://docs.scipy.org/doc/scipy"
@@ -291,7 +289,7 @@ def get_minor_version(package_name: str) -> str:
 nb_execution_mode = "off"
 if "EXECUTE_NB" in os.environ:
     print("\033[93;1mWill run Jupyter notebooks!\033[0m")
-    nb_execution_mode = "force"
+    nb_execution_mode = "cache"
 
 # Settings for myst-parser
 myst_enable_extensions = [