Use the shared starlight-theme for the docs

.github/workflows/docs.yml

@@ -1,7 +1,8 @@
 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; deployed to GitHub Pages from devel.
+# The Astro + Starlight site in docs/: hand-written pages, the executed notebooks 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.
 
 on:
   push:
@@ -20,65 +21,17 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: bash
-    steps:
-      - uses: actions/checkout@v7
-
-      - uses: astral-sh/setup-uv@v7
-        with:
-          python-version: "3.12"
-          enable-cache: true
-
-      - uses: actions/setup-node@v7
-        with:
-          node-version: 22
-          cache: npm
-          cache-dependency-path: docs/package-lock.json
-
-      - name: Install the package with the docs extra
-        run: |
-          uv sync --extra docs
-          uv run python -m ipykernel install --user --name python3
-
-      - name: Execute and convert the tutorials
-        run: |
-          uv run python docs/tools/notebooks.py execute
-          uv run python docs/tools/notebooks.py convert --strict
-          uv run python docs/tools/examples.py
-
-      - name: Build the site
-        working-directory: docs
-        run: |
-          npm ci
-          npm run check:mdx
-          DOCS_PYTHON="$(pwd)/../.venv/bin/python" npm run build
-
-      - name: Smoke test the built site
-        working-directory: docs
-        run: |
-          for page in /index.html /getting-started/installation/index.html /tutorials/index.html /tutorials/example-tutorial/index.html /full-examples/index.html /full-examples/sine-wave/index.html /api/app/index.html /api/app/main/index.html; do
-            test -f "dist$page" || { echo "missing dist$page"; exit 1; }
-          done
-          test -f dist/tutorials/example-tutorial/example_tutorial.ipynb
-          test -f dist/full-examples/sine-wave/plot-1.png
-          grep -q 'href="/template-python/' dist/index.html || { echo "links do not use the base path"; exit 1; }
-          echo "all pages built with the /template-python base path"
-
-      - uses: actions/upload-pages-artifact@v5
-        with:
-          path: docs/dist
-
-  deploy:
-    needs: build
-    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/devel'
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v5
+  docs:
+    uses: max-models/starlight-theme/.github/workflows/docs.yml@v0.1.0
+    with:
+      pre-build: uv run python docs/tools/examples.py
+      smoke-paths: |
+        getting-started/installation/index.html
+        tutorials/index.html
+        tutorials/example-tutorial/index.html
+        full-examples/index.html
+        full-examples/sine-wave/index.html
+        api/app/index.html
+        api/app/main/index.html
+        tutorials/example-tutorial/example_tutorial.ipynb
+        full-examples/sine-wave/plot-1.png

.github/workflows/test_tutorials.yml

@@ -28,10 +28,19 @@ jobs:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
 
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
       - name: Install project
         run: |
           uv sync --extra docs
           uv run python -m ipykernel install --user --name python3
+          cd docs && npm ci
 
       - name: Execute tutorials
-        run: uv run python docs/tools/notebooks.py execute --force
+        working-directory: docs
+        run: DOCS_PYTHON="$(pwd)/../.venv/bin/python" npx starlight-notebooks execute --force

.gitlab-ci.yml

@@ -43,9 +43,11 @@ pages:
   script:
     - apt-get update && apt-get install -y python3 python3-pip python3-venv
     - pip install uv && uv sync --extra docs
-    - uv run python docs/tools/notebooks.py execute
-    - uv run python docs/tools/notebooks.py convert
-    - cd docs && npm ci && DOCS_PYTHON="$(pwd)/../.venv/bin/python" npm run build
+    - export DOCS_PYTHON="$CI_PROJECT_DIR/.venv/bin/python"
+    - cd docs && npm ci
+    - npx starlight-notebooks execute
+    - npx starlight-notebooks convert
+    - npx astro build
     - mv dist ../public
   artifacts:
     paths:

Makefile

@@ -1,7 +1,7 @@
 # Development environment (uv), README (Quarto) and the documentation site (docs/, Astro + Starlight).
-# Notebook tool: docs/tools/notebooks.py.
+# Notebook tool: starlight-notebooks, from @max-models/starlight-theme (docs/node_modules).
 PYTHON ?= .venv/bin/python
-NOTEBOOKS = $(PYTHON) docs/tools/notebooks.py
+NOTEBOOKS = cd docs && $(DOCS_ENV) npx starlight-notebooks
 DOCS_ENV = DOCS_PYTHON=$(shell $(PYTHON) -c "import sys; print(sys.executable)")
 FORCE ?=
 

docs/.gitignore

@@ -2,7 +2,7 @@
 dist/
 .astro/
 node_modules/
-# generated by docs/tools/notebooks.py (regenerated in CI)
+# generated by starlight-notebooks (regenerated in CI)
 .cache/
 public/tutorials/
 src/content/docs/tutorials/*.mdx

docs/astro.config.mjs

@@ -1,94 +1,42 @@
 // @ts-check
-import { defineConfig } from 'astro/config';
-import { unified } from '@astrojs/markdown-remark';
-import starlight from '@astrojs/starlight';
-import starlightLinksValidator from 'starlight-links-validator';
-import starlightPydocs, { pydocsSidebarGroup } from 'starlight-pydocs';
-import rehypeKatex from 'rehype-katex';
-import remarkMath from 'remark-math';
+// The shared max-models docs setup (@max-models/starlight-theme): served at
+// https://max-models.github.io/template-python/, with math, the API reference and a link check.
+import { defineDocs } from '@max-models/starlight-theme';
 
-// The site is served at https://max-models.github.io/template-python/ by GitHub Pages.
-const base = '/template-python';
-
-// The Python package documented under "API reference" (the directory name in src/).
-const pythonPackage = 'app';
-
-export default defineConfig({
-	site: 'https://max-models.github.io',
-	base,
-	markdown: {
-		// $...$ and $$...$$ math in Markdown and MDX pages, rendered with KaTeX at build time
-		processor: unified({ remarkPlugins: [remarkMath], rehypePlugins: [rehypeKatex] }),
-	},
-	integrations: [
-		starlight({
-			title: 'template-python',
-			description: 'Template repository for Python projects.',
-			customCss: ['katex/dist/katex.min.css', './src/styles/custom.css'],
-			components: {
-				Header: './src/components/Header.astro',
-			},
-			social: [
-				{ icon: 'github', label: 'GitHub', href: 'https://github.com/max-models/template-python' },
-			],
-			editLink: { baseUrl: 'https://github.com/max-models/template-python/edit/devel/docs/' },
-			lastUpdated: true,
-			plugins: [
-				starlightPydocs({
-					packages: [
-						{
-							name: pythonPackage,
-							label: 'All modules',
-							search: ['../src'],
-							docstringStyle: 'google',
-							members: {
-								exclude: [`${pythonPackage}.tests`, `${pythonPackage}.tests.*`],
-							},
-							sourceLink: {
-								host: 'github',
-								repo: 'max-models/template-python',
-								ref: 'devel',
-								root: '..',
-							},
-							sidebar: { collapsed: false },
-						},
-					],
-					// The interpreter griffe runs in (set by `make docs-*`); falls back to uvx / python.
-					runner: process.env.DOCS_PYTHON ? { python: process.env.DOCS_PYTHON } : undefined,
-					inventories: ['python', { url: 'https://numpy.org/doc/stable/objects.inv' }],
-				}),
-				...(process.env.DOCS_VALIDATE_LINKS === 'false'
-					? []
-					: [starlightLinksValidator({ errorOnLocalLinks: false, exclude: [`${base}/api/**`, '/api/**'] })]),
+export default defineDocs({
+	repo: 'template-python',
+	title: 'template-python',
+	description: 'Template repository for Python projects.',
+	pythonPackage: 'app',
+	nav: [
+		{ label: 'Getting started', link: '/getting-started/installation/' },
+		{ label: 'Tutorials', link: '/tutorials/' },
+		{ label: 'Full examples', link: '/full-examples/' },
+		{ label: 'Development', link: '/development/docs/' },
+		{ label: 'API', link: '/api/app/' },
+	],
+	sidebar: [
+		{
+			label: 'Getting started',
+			items: [
+				{ label: 'Installation', slug: 'getting-started/installation' },
+				{ label: 'Quickstart', slug: 'getting-started/quickstart' },
 			],
-			sidebar: [
-				{
-					label: 'Getting started',
-					items: [
-						{ label: 'Installation', slug: 'getting-started/installation' },
-						{ label: 'Quickstart', slug: 'getting-started/quickstart' },
-					],
-				},
-				{
-					label: 'Tutorials',
-					items: [{ autogenerate: { directory: 'tutorials' } }],
-				},
-				{
-					label: 'Full examples',
-					items: [{ autogenerate: { directory: 'full-examples' } }],
-				},
-				{
-					label: 'Development',
-					items: [
-						{ label: 'Building the docs', slug: 'development/docs' },
-						{ label: 'Publishing', slug: 'development/publishing' },
-					],
-				},
-				{
-					label: 'API reference',
-					items: [pydocsSidebarGroup],
-				},
+		},
+		{
+			label: 'Tutorials',
+			items: [{ autogenerate: { directory: 'tutorials' } }],
+		},
+		{
+			label: 'Full examples',
+			items: [{ autogenerate: { directory: 'full-examples' } }],
+		},
+		{
+			label: 'Development',
+			items: [
+				{ label: 'Building the docs', slug: 'development/docs' },
+				{ label: 'Publishing', slug: 'development/publishing' },
 			],
-		}),
+		},
 	],
 });