chore: build documentation with make (#144)

* ci: add jcache tox job * ci: define dependabot for GitHub Actions * ci: fix flake8 linting errors * 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 * style: use 2 spaces indent size in ini files
ComPWA · May 21, 2022 · c3d3047 · c3d3047
1 parent 1af9ff0
commit c3d3047
Show file tree

Hide file tree

Showing 19 changed files with 138 additions and 137 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -44,7 +44,6 @@
         "docs/adr/*/*",
         "docs/conf.py",
         "labels.toml",
-        "Makefile",
         "pyproject.toml",
         "pyrightconfig.json",
         "pytest.ini",

diff --git a/.editorconfig b/.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
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    assignees:
+      - redeboer
+    labels:
+      - 🖱️ DX
+    schedule:
+      interval: monthly
diff --git a/.github/workflows/cd.yml b/.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:

diff --git a/.github/workflows/ci-docs.yml b/.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

diff --git a/.github/workflows/linkcheck.yml b/.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
diff --git a/.github/workflows/requirements-cron.yml b/.github/workflows/requirements-cron.yml
@@ -17,7 +17,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 }}
@@ -26,7 +26,7 @@ jobs:
     name: pre-commit autoupdate
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ComPWA/update-pre-commit@main
 
   push:
@@ -36,7 +36,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

diff --git a/.github/workflows/requirements-pr.yml b/.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

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -48,7 +48,7 @@ repos:
           )$
 
   - repo: https://github.com/ComPWA/repo-maintenance
-    rev: 0.0.124
+    rev: 0.0.127
     hooks:
       - id: check-dev-files
         args:
@@ -79,7 +79,9 @@ repos:
       - id: editorconfig-checker
         exclude: >
           (?x)^(
-            .*\.py
+            .*\.md|
+            .*\.py|
+            LICENSE
           )$
 
   - repo: https://github.com/pycqa/isort

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
@@ -4,5 +4,5 @@
 {% endif -%}
 .. automodule:: {{ qualname }}
 {%- for option in automodule_options %}
-   :{{ option }}:
+  :{{ option }}:
 {%- endfor %}
diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t
@@ -1,14 +1,14 @@
 {%- 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 %}
 

diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t
@@ -1,7 +1,7 @@
 {{ header | heading }}
 
 .. toctree::
-   :maxdepth: {{ maxdepth }}
+  :maxdepth: {{ maxdepth }}
 {% for docname in docnames %}
-   {{ docname }}
+  {{ docname }}
 {%- endfor %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -286,7 +286,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 = [

diff --git a/docs/develop.md b/docs/develop.md
@@ -454,19 +454,6 @@ You can quickly build the documentation with the command:
 tox -e doc
 ```
 
-:::{toggle}
-
-Alternatively, you can run
-[`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html)
-yourself as follows:
-
-```shell
-cd docs
-make html
-```
-
-:::
-
 <!-- cspell:ignore autobuild -->
 
 If you are doing a lot of work on the documentation,

diff --git a/docs/report/005.ipynb b/docs/report/005.ipynb
@@ -123,7 +123,7 @@
     "import numpy as np\n",
     "import symplot\n",
     "import sympy as sp\n",
-    "from IPython.display import Image, Math\n",
+    "from IPython.display import Math\n",
     "from ipywidgets import widgets as ipywidgets\n",
     "from matplotlib import cm\n",
     "from mpl_interactions.controller import Controls\n",

diff --git a/pyproject.toml b/pyproject.toml
@@ -37,5 +37,5 @@ profile = "black"
 
 [tool.nbqa.addopts]
 flake8 = [
-    "--extend-ignore=E402,F821",
+    "--extend-ignore=E402,F404,F821",
 ]
diff --git a/pytest.ini b/pytest.ini
@@ -1,18 +1,18 @@
 [pytest]
 addopts =
-    --color=yes
-    --durations=0
-    --ignore=docs/adr/001/sympy.ipynb
-    --ignore=docs/conf.py
-    --ignore-glob=*/.ipynb_checkpoints/*
+  --color=yes
+  --durations=0
+  --ignore-glob=*/.ipynb_checkpoints/*
+  --ignore=docs/adr/001/sympy.ipynb
+  --ignore=docs/conf.py
 filterwarnings =
-    error
-    ignore:Passing a schema to Validator.iter_errors is deprecated.*:DeprecationWarning
-    ignore:The .* argument to NotebookFile is deprecated.*:pytest.PytestRemovedIn8Warning
-    ignore:open_text is deprecated.*:DeprecationWarning
-    ignore:read_text is deprecated.*:DeprecationWarning
-    ignore:unclosed .*:ResourceWarning
+  error
+  ignore:Passing a schema to Validator.iter_errors is deprecated.*:DeprecationWarning
+  ignore:The .* argument to NotebookFile is deprecated.*:pytest.PytestRemovedIn8Warning
+  ignore:open_text is deprecated.*:DeprecationWarning
+  ignore:read_text is deprecated.*:DeprecationWarning
+  ignore:unclosed .*:ResourceWarning
 norecursedirs =
-    _build
+  _build
 testpaths =
-    docs
+  docs