ENH!: build documentation with Quarto

.cspell.json

@@ -21,6 +21,8 @@
   "ignorePaths": [
     "**/*.bib",
     "**/.cspell.json",
+    "**/_extensions/**",
+    "*.csl",
     "*.ico",
     ".editorconfig",
     ".envrc",
@@ -31,10 +33,10 @@
     ".taplo.toml",
     ".vscode/*",
     "codecov.yml",
-    "docs/conf.py",
     "pyproject.toml"
   ],
   "ignoreWords": [
+    "Aitchison",
     "Badalian",
     "Colab",
     "IPython",
@@ -50,21 +52,16 @@
     "compwa",
     "concat",
     "dateutil",
-    "docnb",
     "eval",
     "expertsystem",
     "figsize",
     "fontsize",
     "frameon",
     "genindex",
-    "graphviz",
     "htmlcov",
     "infty",
-    "ipykernel",
-    "ipynb",
     "isinstance",
     "isort",
-    "jupyterlab",
     "kernelspec",
     "kutschke",
     "labelpar",
@@ -77,6 +74,8 @@
     "multiplets",
     "nbconvert",
     "nbformat",
+    "nbsp",
+    "nocite",
     "noreply",
     "notcited",
     "oneline",
@@ -128,6 +127,7 @@
     "brookhaven",
     "checkmark",
     "chromodynamics",
+    "CLAS12",
     "clebsch",
     "conda",
     "Cuda",
@@ -155,6 +155,7 @@
     "sympy",
     "unitarity",
     "unstaged",
-    "zemach"
+    "zemach",
+    "zfit"
   ]
 }

.editorconfig

@@ -7,8 +7,8 @@ indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{ipynb,md}]
-indent_size = 1
+[*.{csl,md,qmd}]
+indent_size = unset
 
 [*.{py,toml}]
 indent_size = 4

.gitignore

@@ -1,16 +1,3 @@
-# Output files
-*.gv
-*.json
-*.npy
-*.pdf
-*.pickle
-*.png
-*.svg
-*.v2
-*.xml
-*.yaml
-*.yml
-
 # Build files
 *.egg-info/
 *build/
@@ -40,11 +27,8 @@ pyvenv*/
 **.code-workspace
 
 # Exceptions
-!.cspell.json
 !.github/*.yml
 !.github/*/*.yml
 !.pre-commit-config.yaml
 !.readthedocs.yml
-!.vscode/*.json
 !codecov.yml
-!pyrightconfig.json

.pre-commit-config.yaml

@@ -16,58 +16,23 @@ repos:
       - id: check-useless-excludes
 
   - repo: https://github.com/ComPWA/policy
-    rev: 0.7.3
+    rev: 0.7.4
     hooks:
       - id: check-dev-files
         args:
           - --ci-skipped-tests=all
           - --macos-python-version=disable
-          - --no-binder
           - --no-cd
           - --no-pypi
           - --repo-name=PWA-pages
           - --repo-title=PWA Pages
-      - id: colab-toc-visible
-      - id: fix-nbformat-version
-      - id: remove-empty-tags
-      - id: set-nb-display-name
-
-  - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.1
-    hooks:
-      - id: nbstripout
-        args:
-          - --drop-empty-cells
-          - --extra-keys
-          - |
-            cell.attachments
-            cell.metadata.code_folding
-            cell.metadata.editable
-            cell.metadata.id
-            cell.metadata.pycharm
-            cell.metadata.slideshow
-            cell.metadata.user_expressions
-            metadata.celltoolbar
-            metadata.colab.name
-            metadata.colab.provenance
-            metadata.interpreter
-            metadata.notify_time
-            metadata.toc
-            metadata.toc-autonumbering
-            metadata.toc-showcode
-            metadata.toc-showmarkdowntxt
-            metadata.toc-showtags
-            metadata.varInspector
-            metadata.vscode
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.0
+    rev: v0.14.1
     hooks:
       - id: ruff-check
         args: [--fix]
-        types_or: [python, pyi, jupyter]
       - id: ruff-format
-        types_or: [python, pyi, jupyter]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -161,6 +126,6 @@ repos:
         files: (docs/software/.*\.json|src/pwa_pages/project_inventory.py)
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.2
+    rev: 0.9.4
     hooks:
       - id: uv-lock

.prettierignore

@@ -1,3 +1,2 @@
-*.ipynb
 LICENSE
 docs/software/*.json

.prettierrc.yml

@@ -0,0 +1,7 @@
+overrides:
+  - files: "**.code-snippets"
+    options:
+      parser: json
+  - files: "**.qmd"
+    options:
+      parser: markdown

.readthedocs.yml

@@ -8,7 +8,7 @@ build:
     - |-
       export PIXI_HOME=$READTHEDOCS_VIRTUALENV_PATH
       curl -fsSL https://pixi.sh/install.sh | bash
-      pixi global install graphviz uv
+      pixi global install uv
     - |-
       export UV_LINK_MODE=copy
       uv run \
@@ -18,6 +18,3 @@ build:
         poe doc
       mkdir -p $READTHEDOCS_OUTPUT
       mv docs/_build/html $READTHEDOCS_OUTPUT
-
-sphinx:
-  configuration: docs/conf.py

.vscode/extensions.json

@@ -5,17 +5,15 @@
     "eamodio.gitlens",
     "editorconfig.editorconfig",
     "esbenp.prettier-vscode",
-    "executablebookproject.myst-highlight",
     "github.vscode-github-actions",
     "github.vscode-pull-request-github",
     "mhutchie.git-graph",
     "ms-python.mypy-type-checker",
     "ms-python.python",
     "ms-python.vscode-pylance",
-    "ms-toolsai.jupyter",
-    "ms-toolsai.vscode-jupyter-cell-tags",
     "ms-vscode.live-server",
     "ms-vsliveshare.vsliveshare",
+    "quarto.quarto",
     "redhat.vscode-yaml",
     "soulcode.vscode-unwanted-extensions",
     "stkb.rewrap",
@@ -26,11 +24,14 @@
   "unwantedRecommendations": [
     "bungcip.better-toml",
     "davidanson.vscode-markdownlint",
+    "executablebookproject.myst-highlight",
     "garaioag.garaio-vscode-unwanted-recommendations",
     "ms-python.black-formatter",
     "ms-python.flake8",
     "ms-python.isort",
     "ms-python.pylint",
+    "ms-toolsai.jupyter",
+    "ms-toolsai.vscode-jupyter-cell-tags",
     "ms-toolsai.vscode-jupyter-slideshow",
     "ryanluker.vscode-coverage-gutters",
     "travisillig.vscode-json-stable-stringify",

.vscode/quarto.code-snippets

@@ -0,0 +1,20 @@
+{
+  "Quarto Todo item (margin)": {
+    "scope": "quarto",
+    "prefix": "quarto-todo-margin",
+    "body": [
+      "::::{.column-margin}",
+      ":::{.callout-warning title=\"To do\"}",
+      "$0",
+      ":::",
+      "::::"
+    ],
+    "description": "Insert a to-do note in the margin"
+  },
+  "Quarto Todo item": {
+    "scope": "quarto",
+    "prefix": "quarto-todo",
+    "body": [":::{.callout-warning title=\"To do\"}", "$0", ":::"],
+    "description": "Insert a to-do note"
+  }
+}

.vscode/settings.json

@@ -23,6 +23,12 @@
     "editor.defaultFormatter": "charliermarsh.ruff",
     "editor.rulers": [88]
   },
+  "[quarto]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[snippets]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
   "[yaml]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -35,17 +41,12 @@
   "livePreview.defaultPreviewPath": "docs/_build/html",
   "multiDiffEditor.experimental.enabled": true,
   "mypy-type-checker.args": ["--config-file=${workspaceFolder}/pyproject.toml"],
-  "myst.preview.extensions": [
-    "amsmath",
-    "colon_fence",
-    "dollarmath",
-    "tasklist"
-  ],
   "notebook.codeActionsOnSave": {
     "notebook.source.organizeImports": "explicit"
   },
   "notebook.formatOnSave.enabled": true,
   "notebook.gotoSymbols.showAllSymbols": true,
+  "prettier.documentSelectors": ["**/*.qmd"],
   "python.analysis.autoImportCompletions": false,
   "python.analysis.inlayHints.pytestParameters": true,
   "python.defaultInterpreterPath": ".venv/bin/python",
@@ -54,6 +55,7 @@
   "python.testing.pytestArgs": ["--numprocesses=auto"],
   "python.testing.pytestEnabled": true,
   "python.testing.unittestEnabled": false,
+  "quarto.path": ".venv/bin/quarto",
   "redhat.telemetry.enabled": false,
   "rewrap.wrappingColumn": 88,
   "ruff.enable": true,

README.md

@@ -1,18 +1,17 @@
 # Welcome to the Partial Wave Analysis pages!
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
-[![Documentation build status](https://readthedocs.org/projects/pwa/badge/?version=latest)](https://pwa.readthedocs.io)
+[![Documentation build status](https://app.readthedocs.org/projects/pwa/badge)](https://pwa.readthedocs.io)
 [![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/PWA-pages)
-[![CI status](https://github.com/ComPWA/PWA-pages/workflows/CI/badge.svg)](https://github.com/ComPWA/PWA-pages/actions?query=branch%3Amain+workflow%3ACI)
+[![CI](https://github.com/ComPWA/PWA-pages/actions/workflows/ci.yml/badge.svg)](https://github.com/ComPWA/PWA-pages/actions/workflows/ci.yml)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)](https://github.com/pre-commit/pre-commit)
 [![Test coverage](https://codecov.io/gh/ComPWA/PWA-pages/branch/main/graph/badge.svg)](https://codecov.io/gh/ComPWA/PWA-pages)
 [![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 
-This repository contains the source code for the
-[pwa.rtfd.io](https://pwa.readthedocs.io) pages.
+This repository contains the source code for the [pwa.rtfd.io](https://pwa.readthedocs.io) pages.
 
 ## Contribute
 

docs/.gitignore

@@ -1,6 +1,15 @@
+.jupyter_cache/
+*_files/
 *.doctree
+*.epub
+*.html
 *.inv
+*.pdf
+*.quarto_ipynb
 *build/
-api/
+/.quarto/
+site_libs/
 
 !_static/*
+
+**/*.quarto_ipynb

docs/_extensions/debruine/glossary/_extension.yml

@@ -0,0 +1,7 @@
+title: Glossary
+author: Lisa DeBruine
+version: 1.0.0
+quarto-required: ">=1.2.0"
+contributes:
+  shortcodes:
+    - glossary.lua