Move the docs from Sphinx to starlight-theme

.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,24 @@ 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.4.0
+    with:
+      apt-packages: "texlive-latex-base texlive-latex-extra texlive-pictures texlive-fonts-recommended lmodern"
+      # stable-branch: main  # deploy the latest release at /<repo>/ and devel at /<repo>/dev/
+      smoke-paths: |
+        getting-started/installation/index.html
+        getting-started/quickstart/index.html
+        guides/matplotlib-import/index.html
+        tutorials/index.html
+        tutorials/tutorial-01/index.html
+        tutorials/tutorial-07-tikz/index.html
+        tutorials/tutorial-17-xarray/index.html
+        tutorials/tutorial-07-tikz/1.png
+        tutorials/tutorial-01/tutorial_01.ipynb
+        api/maxplotlib/index.html
+        api/maxplotlib/canvas/index.html

.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

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 npx astro dev
+
+docs-build:  ## the static site in docs/dist, as in CI
+	$(NOTEBOOKS) convert
+	cd docs && npx starlight-check-mdx && $(DOCS_ENV) npx astro build
+
+docs-preview:  ## serve docs/dist
+	cd docs && npx astro preview
+
+docs-clean:  ## remove generated pages, assets and build output
+	$(NOTEBOOKS) clean
+	rm -rf docs/dist docs/.astro

docs/.gitignore

@@ -0,0 +1,8 @@
+# Astro
+dist/
+.astro/
+node_modules/
+# generated by starlight-notebooks (regenerated in CI)
+.cache/
+public/tutorials/
+src/content/docs/tutorials/*.mdx

docs/astro.config.mjs

@@ -0,0 +1,56 @@
+// @ts-check
+// The shared max-models docs setup (@max-models/starlight-theme): served at
+// https://max-models.github.io/maxplotlib/, with math, the API reference and a link check.
+import { defineDocs } from '@max-models/starlight-theme';
+
+// The tutorial pages of the old Sphinx site (tutorials/tutorial_01.html, ...)
+const tutorials = [
+	'tutorial_01',
+	'tutorial_02',
+	'tutorial_03',
+	'tutorial_04',
+	'tutorial_05',
+	'tutorial_06',
+	'tutorial_07_tikz',
+	'tutorial_08_plotly',
+	'tutorial_09_plotext',
+	'tutorial_10_matplotlib_nxm_spacing',
+	'tutorial_11_gantt_charts',
+	'tutorial_12_flame_charts',
+	'tutorial_13_advanced_matplotlib',
+	'tutorial_14_axis_and_layout_controls',
+	'tutorial_15_tikzfigure_subplots',
+	'tutorial_16_plotext_advanced',
+	'tutorial_17_xarray',
+];
+
+export default defineDocs({
+	repo: 'maxplotlib',
+	title: 'maxplotlib',
+	description: 'A reproducible plotting module with Matplotlib, Plotly, plotext and TikZ backends.',
+	pythonPackage: 'maxplotlib',
+	nav: [
+		{ label: 'Getting started', link: '/getting-started/installation/' },
+		{ label: 'Tutorials', link: '/tutorials/' },
+		{ label: 'Guides', link: '/guides/matplotlib-import/' },
+		{ label: 'Development', link: '/development/docs/' },
+		{ label: 'API', link: '/api/maxplotlib/', section: '/api/' },
+	],
+	sidebar: [
+		{
+			label: 'Getting started',
+			items: [
+				{ label: 'Installation', slug: 'getting-started/installation' },
+				{ label: 'Quickstart', slug: 'getting-started/quickstart' },
+			],
+		},
+		{ label: 'Tutorials', items: [{ autogenerate: { directory: 'tutorials' } }] },
+		{ label: 'Guides', items: [{ autogenerate: { directory: 'guides' } }] },
+		{ label: 'Development', items: [{ label: 'Building the docs', slug: 'development/docs' }] },
+	],
+	astro: {
+		redirects: Object.fromEntries(
+			tutorials.map((name) => [`/tutorials/${name}.html`, `/tutorials/${name.replaceAll('_', '-')}/`])
+		),
+	},
+});