DX: build documentation through sphinx-build (#25)

* DOC: add website favicon
* DOC: add website icons to sidebar
* DOC: convert STRONG2020 logo to SVG
* DX: add Hypothesis.is overlay for commenting to website
* DX: implement autoformatters for TOML files
* ENH: update documentation requirements
* MAINT: define dependencies in pyproject instead of `requirements.txt`
* MAINT: extend `.gitignore` structure

.editorconfig

@@ -9,3 +9,6 @@ trim_trailing_whitespace = true
 
 [*.{ipynb,md}]
 indent_size = unset
+
+[*.{py,toml}]
+indent_size = 4

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - main
+      - epic/*
+      - "[0-9]+.[0-9]+.x"
+  pull_request:
+    branches:
+      - main
+      - epic/*
+      - "[0-9]+.[0-9]+.x"
+  workflow_dispatch:
+    inputs:
+      specific-pip-packages:
+        description: Run CI with specific pip packages
+        required: false
+        type: string
+
+jobs:
+  style:
+    if: inputs.specific-pip-packages == ''
+    secrets:
+      token: ${{ secrets.PAT }}
+    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v1

.github/workflows/docs.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: "3.10"
-      - run: pip install -r requirements.txt
+      - run: pip install -e .[doc] tox
       - name: Fetch Jupyter cache
         uses: actions/cache@v3
         with:
@@ -36,7 +36,7 @@ jobs:
             data
           path: |
             ./docs/data
-      - run: jupyter book build docs/ -W
+      - run: tox -e docnb
       - uses: actions/upload-pages-artifact@v2
         if: always()
         with:

.gitignore

@@ -1,9 +1,44 @@
+# Output files
 *.csv
 *.dat
 *.txt
+data/
+
+# Build files
+*.egg-info/
+*build/
+.eggs/
+.fuse_*
+dist/
+version.py
+
+# Temporary files
+*.pyc
+*condaenv.*
+.coverage
+.coverage.*
 .ipynb_checkpoints/
+.mypy*/
 .pytest_cache/
 .virtual_documents/
+__pycache__/
 _build/
-data/
-docs/lecture18
+htmlcov/
+jupyter_execute/
+prof/
+
+# Virtual environments
+*venv/
+.tox/
+pyvenv*/
+
+# Settings
+.idea/
+**.code-workspace
+
+# Exceptions
+!.github/*.yml
+!.github/*/*.yml
+!.pre-commit-config.yaml
+!.vscode/*.json
+!environment.yml

.pre-commit-config.yaml

@@ -1,6 +1,8 @@
 ci:
   autoupdate_commit_msg: "MAINT: update pre-commit config file"
   autoupdate_schedule: quarterly
+  skip:
+    - taplo
 
 repos:
   - repo: meta
@@ -13,6 +15,7 @@ repos:
     hooks:
       - id: check-case-conflict
       - id: check-json
+      - id: check-toml
       - id: check-yaml
       - id: end-of-file-fixer
       - id: mixed-line-ending
@@ -84,3 +87,15 @@ repos:
     rev: v3.0.3
     hooks:
       - id: prettier
+
+  - repo: https://github.com/ComPWA/mirrors-taplo
+    rev: v0.8.1
+    hooks:
+      - id: taplo
+
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.23.1
+    hooks:
+      - id: toml-sort
+        args:
+          - --in-place

.taplo.toml

@@ -0,0 +1,12 @@
+[formatting]
+align_comments = false
+align_entries = false
+allowed_blank_lines = 1
+array_auto_collapse = false
+array_auto_expand = true
+array_trailing_comma = true
+column_width = 88
+compact_inline_tables = true
+indent_string = "    "
+reorder_arrays = true
+reorder_keys = true

.vscode/extensions.json

@@ -8,16 +8,20 @@
     "github.vscode-github-actions",
     "github.vscode-pull-request-github",
     "mhutchie.git-graph",
+    "ms-python.black-formatter",
+    "ms-python.isort",
     "ms-python.python",
     "ms-toolsai.jupyter",
     "ms-toolsai.vscode-jupyter-cell-tags",
     "ms-toolsai.vscode-jupyter-slideshow",
     "ms-vscode.live-server",
     "stkb.rewrap",
+    "tamasfe.even-better-toml",
     "tyriar.sort-lines",
     "yzhang.markdown-all-in-one"
   ],
   "unwantedRecommendations": [
+    "bungcip.better-toml",
     "davidanson.vscode-markdownlint",
     "ms-python.mypy-type-checker",
     "travisillig.vscode-json-stable-stringify"

.vscode/settings.json

@@ -3,7 +3,29 @@
     "editor.rulers": [72],
     "rewrap.wrappingColumn": 72
   },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[python]": {
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": true
+    },
+    "editor.defaultFormatter": "ms-python.black-formatter",
+    "editor.rulers": [88]
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "black-formatter.importStrategy": "useBundled",
   "editor.formatOnSave": true,
+  "github-actions.workflows.pinned.workflows": [".github/workflows/ci.yml"],
+  "isort.args": ["--profile", "black"],
   "livePreview.defaultPreviewPath": "docs/_build/html",
   "notebook.gotoSymbols.showAllSymbols": true,
   "rewrap.wrappingColumn": 88

README.md

@@ -25,10 +25,20 @@ This (unofficial) repository contains the exercises for the [STRONG2020 HaSP Sch
 
 ## Documentation
 
-The website [compwa.github.io/strong2020-salamanca](https://compwa.github.io/strong2020-salamanca) is automatically generated from the notebooks in this repository using [Jupyter Book](https://jupyterbook.org). You can also run the notebooks and build the documentation locally as follows:
+The website [compwa.github.io/strong2020-salamanca](https://compwa.github.io/strong2020-salamanca) is automatically generated from the notebooks in this repository using [Sphinx](https://www.sphinx-doc.org) and [MyST-NB](https://myst-nb.rtfd.io). You can also run the notebooks and build the documentation locally as follows:
 
 ```shell
-jb build docs/
+tox -e docnb
 ```
 
-Adding the flag `-W` renders warnings as errors, which is useful for checking whether the notebooks run correctly.
+Alternatively, you can run the notebooks without building the documentation with
+
+```shell
+tox -e nb
+```
+
+or build the documentation without running the notebooks with
+
+```shell
+tox -e doc
+```

docs/.gitignore

@@ -0,0 +1 @@
+lecture18

docs/_toc.yml

@@ -1,4 +1,3 @@
-format: jb-book
 root: index
-chapters:
+entries:
   - glob: lecture*