Release 0.3.0

.gitattributes

@@ -1 +1 @@
-*.ipynb filter=strip-notebook-output  
+*.ipynb filter=strip-notebook-output

.github/workflows/ci_pipeline.yml

@@ -44,7 +44,7 @@ jobs:
         run: |
           coverage run -m pytest .
           coverage report --sort=cover
-      
+
       - name: Test tutorials
         run: |
           jupyter nbconvert --to notebook --execute tutorials/*.ipynb \

.github/workflows/docs.yml

@@ -1,8 +1,15 @@
-name: Deploy docs to GitHub Pages
+name: Docs
+
+# The Astro + Starlight site in docs/: hand-written pages, the executed tutorials and the API
+# reference. Built on every push and pull request with the shared workflow of
+# max-models/starlight-theme; deployed to GitHub Pages from devel.
+# The TikZ tutorials compile their figures with pdflatex and pgfplots, hence the LaTeX packages.
 
 on:
   push:
-    branches: ["devel", "main"] # TODO: Set to main only after release
+    branches: ["main", "devel"]
+  pull_request:
+    branches: ["main", "devel"]
   workflow_dispatch:
 
 permissions:
@@ -11,49 +18,32 @@ permissions:
   id-token: write
 
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  build-and-deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install pandoc and LaTeX
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y pandoc
-          # pdflatex with pgfplots: the tutorials compile tikzfigure figures
-          sudo apt-get install -y --no-install-recommends \
-            texlive-latex-base texlive-latex-extra texlive-pictures \
-            texlive-fonts-recommended lmodern
-
-      - name: Install Python dependencies
-        run: |
-          python -m pip install --upgrade pip
-          # tikzfigure 0.4.0 is not on PyPI yet: install it from GitHub (drop once released)
-          pip install "tikzfigure[vis] @ git+https://github.com/max-models/tikzfigure@c290f43ac1deb4a4ed3b5b40919f10d3a6b53e8b"
-          pip install ".[docs]"
-
-      - name: Build Sphinx docs
-        run: |
-          cd docs
-          make html
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-
-      - name: Upload built docs
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/build/html/
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+  docs:
+    uses: max-models/starlight-theme/.github/workflows/docs.yml@v0
+    with:
+      apt-packages: "texlive-latex-base texlive-latex-extra texlive-pictures texlive-fonts-recommended lmodern"
+      # the example web figures of guides/web-figures, from scripts/web_figure_examples.py
+      pre-build: '"$DOCS_PYTHON" scripts/web_figure_examples.py'
+      # stable-branch: main  # deploy the latest release at /<repo>/ and devel at /<repo>/dev/
+      # a notebook's outputs are numbered in order: in tutorial 07, 1.html is the Plotly
+      # preview and 2.png the first compiled TikZ figure
+      smoke-paths: |
+        getting-started/installation/index.html
+        getting-started/quickstart/index.html
+        guides/matplotlib-import/index.html
+        guides/web-figures/index.html
+        figures/waves.plotly.json
+        figures/heatmap.plotly.json
+        figures/packet.plotly.json
+        tutorials/index.html
+        tutorials/tutorial-01/index.html
+        tutorials/tutorial-07-tikz/index.html
+        tutorials/tutorial-17-xarray/index.html
+        tutorials/tutorial-07-tikz/2.png
+        tutorials/tutorial-01/tutorial_01.ipynb
+        api/maxplotlib/index.html
+        api/maxplotlib/canvas/index.html

.github/workflows/publish.yml

@@ -31,4 +31,3 @@ jobs:
           TWINE_USERNAME: __token__  # Use API token
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: twine upload dist/*
-

.github/workflows/static_analysis.yml

@@ -24,57 +24,6 @@ jobs:
           ./cloc --version
           ./cloc $(git ls-files)
 
-  black:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the code
-        uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Code formatting with black
-        run: |
-          pip install "black[jupyter]"
-          black --check src/
-          black --check tutorials/
-
-  isort:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the code
-        uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Code formatting with isort
-        run: |
-          pip install isort
-          isort --check src/
-          isort --check tutorials/
-
-  mypy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout the code
-        uses: actions/checkout@v4
-
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Type check with mypy
-        continue-on-error: true
-        run: |
-          pip install mypy
-          mypy src/
-
   prospector:
     runs-on: ubuntu-latest
     steps:
@@ -103,11 +52,18 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Lint with ruff
-        continue-on-error: true
+      - name: Linting with ruff (including import sorting)
         run: |
           pip install ruff
-          ruff check src/
+          ruff check .
+
+      - name: Code formatting with ruff
+        run: ruff format --check .
+
+      - name: Check statement order
+        run: |
+          pip install ssort
+          ssort --check --diff .
 
   pylint:
     runs-on: ubuntu-latest

.gitignore

@@ -68,8 +68,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
 
 # PyBuilder
 .pybuilder/
@@ -172,6 +170,11 @@ figures/
 *.mp4
 *.pkl
 *.json
+# except the docs site and Renovate config
+!docs/package.json
+!docs/package-lock.json
+!docs/tsconfig.json
+!renovate.json
 
 # tex
 *.aux
@@ -197,3 +200,5 @@ docs/superpowers/
 docs/tutorials/
 tutorials/*.txt
 tutorials/*.png
+tutorials/*.tikz
+tutorials/*.html

.pre-commit-config.yaml

@@ -1,15 +1,27 @@
+---
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0  # Use the latest stable version
+    rev: v6.0.0
     hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
       - id: check-added-large-files # Prevent giant files from being committed.
-        args: ["--maxkb=1000"]     
-      - id: check-merge-conflict    # Check for files that contain merge conflict strings.
-      - id: check-toml              # Attempts to load all TOML files to verify syntax.
-      - id: check-yaml              # Attempts to load all yaml files to verify syntax.
-        args: ["--unsafe"]
-
+        args: [--maxkb=500]
+        exclude: ^(uv\.lock|docs/package-lock\.json)$ # generated lock files
+      - id: check-merge-conflict # Check for files that contain merge conflict strings.
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.1
+    rev: 0.9.1
     hooks:
-      - id: nbstripout # remove jupyter notebook cell output
+      - id: nbstripout # strip jupyter notebook output
+  - repo: https://github.com/bwhmather/ssort
+    rev: 0.17.0
+    hooks:
+      - id: ssort # order statements so names are defined before they are used
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.3
+    hooks:
+      - id: ruff-check # lint, including import sorting (the I rules)
+        args: [--fix]
+      - id: ruff-format

Makefile

@@ -0,0 +1,33 @@
+# The documentation site (docs/, Astro + Starlight).
+# Notebook tool: starlight-notebooks, from @max-models/starlight-theme (docs/node_modules).
+PYTHON ?= .venv/bin/python
+DOCS_ENV = DOCS_PYTHON=$(abspath $(PYTHON))
+NOTEBOOKS = cd docs && $(DOCS_ENV) npx starlight-notebooks
+
+.PHONY: help docs-install docs-notebooks docs-dev docs-build docs-preview docs-clean
+
+help:  ## list the targets
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-16s %s\n", $$1, $$2}'
+
+docs-install:  ## Python docs extra and the npm packages
+	$(PYTHON) -m pip install -e ".[docs]"
+	cd docs && npm ci
+
+docs-notebooks:  ## execute the changed tutorials and convert all of them (FORCE=1 reruns all)
+	$(NOTEBOOKS) execute $(if $(FORCE),--force,)
+	$(NOTEBOOKS) convert
+
+docs-dev:  ## live preview at http://localhost:4321/maxplotlib/
+	$(NOTEBOOKS) convert
+	cd docs && $(DOCS_ENV) DOCS_VALIDATE_LINKS=false npm run dev
+
+docs-build:  ## the static site in docs/dist, as in CI
+	$(NOTEBOOKS) convert
+	cd docs && npm run check:mdx && $(DOCS_ENV) npm run build
+
+docs-preview:  ## serve docs/dist
+	cd docs && npm run preview
+
+docs-clean:  ## remove generated pages, assets and build output
+	$(NOTEBOOKS) clean
+	rm -rf docs/dist docs/.astro