Version 0.5.0

.github/actions/build-docs/action.yml

@@ -1,20 +1,20 @@
 name: "Build Documentation"
-description: "Build Astro/Starlight documentation"
+description: "Execute the tutorial notebooks and build the Astro/Starlight documentation"
 inputs:
   python-version:
     description: "Python version to use"
     required: false
     default: "3.12"
-  build-tutorials:
-    description: "Whether to generate tutorial markdown/assets"
+  execute-notebooks:
+    description: "Whether to execute the tutorial notebooks (into astro_docs/.cache/notebooks)"
     required: false
     default: "true"
-  tutorial-build-args:
-    description: "Extra arguments passed to build_tutorials.py"
+  notebook-directory:
+    description: "Execute only the notebooks in this directory of tutorials/ (a CI shard)"
     required: false
     default: ""
   build-site:
-    description: "Whether to build the Astro site"
+    description: "Whether to convert the executed notebooks into pages and build the Astro site"
     required: false
     default: "true"
 runs:
@@ -25,6 +25,11 @@ runs:
       with:
         python-version: ${{ inputs.python-version }}
 
+    - name: Set up Node
+      uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
     - name: Check if pdflatex is available
       shell: bash
       run: |
@@ -36,20 +41,43 @@ runs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install ".[docs]"
+        python -m ipykernel install --user --name python3
+        echo "DOCS_PYTHON=$(command -v python)" >> "$GITHUB_ENV"
+
+    - name: Install the npm packages
+      shell: bash
+      working-directory: astro_docs
+      run: npm ci
+
+    - name: Execute the tutorial notebooks
+      if: ${{ inputs.execute-notebooks == 'true' }}
+      shell: bash
+      working-directory: astro_docs
+      run: |
+        if [ -n "${{ inputs.notebook-directory }}" ]; then
+          npx starlight-notebooks execute --source "../tutorials/${{ inputs.notebook-directory }}" --section tutorials
+        else
+          npx starlight-notebooks execute
+        fi
 
-    - name: Build tutorials (Quarto + Jupyter → Markdown)
-      if: ${{ inputs.build-tutorials == 'true' }}
+    - name: Convert the notebooks into pages
+      if: ${{ inputs.build-site == 'true' }}
       shell: bash
-      run: python astro_docs/scripts/build_tutorials.py ${{ inputs.tutorial-build-args }}
+      working-directory: astro_docs
+      run: |
+        npx starlight-notebooks convert --strict
+        npx starlight-check-mdx
 
     - name: Build and upload site
       if: ${{ inputs.build-site == 'true' }}
       uses: withastro/action@v5
       with:
         path: astro_docs
 
+    # The links in the pages carry the /tikzfigure base path, so they cannot all resolve in a
+    # site served from /; the link check already ran on the real build above.
     - name: Rebuild without base path for local artifact inspection
       if: ${{ inputs.build-site == 'true' }}
       shell: bash
       working-directory: astro_docs
-      run: npx astro build --base /
+      run: DOCS_VALIDATE_LINKS=false npx astro build --base /

.github/workflows/test_docs.yml

@@ -32,21 +32,20 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Build tutorial directory
+      - name: Execute the notebooks of one tutorial directory
         uses: ./.github/actions/build-docs
         with:
           python-version: "3.12"
           build-site: "false"
-          tutorial-build-args: --serial --directory ${{ matrix.tutorial-dir }}
+          notebook-directory: ${{ matrix.tutorial-dir }}
 
       - name: Upload tutorial directory artifact
         uses: actions/upload-artifact@v4
         if: always()
         with:
           name: tutorials-dir-${{ matrix.tutorial-dir }}
-          path: |
-            astro_docs/src/content/docs/tutorials/
-            astro_docs/public/tutorials/
+          path: astro_docs/.cache/notebooks/
+          include-hidden-files: true
           retention-days: 7
 
   test-docs:
@@ -66,14 +65,14 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           pattern: tutorials-dir-*
-          path: astro_docs
+          path: astro_docs/.cache/notebooks
           merge-multiple: true
 
       - name: Build documentation
         uses: ./.github/actions/build-docs
         with:
           python-version: "3.12"
-          build-tutorials: "false"
+          execute-notebooks: "false"
 
       - name: Upload docs artifact
         uses: actions/upload-artifact@v4

astro_docs/.gitignore

@@ -3,7 +3,8 @@ dist/
 # generated types
 .astro/
 
-# generated by astro_docs/scripts/build_tutorials.py
+# generated by starlight-notebooks
+.cache/
 src/content/docs/tutorials/
 public/tutorials/
 

astro_docs/astro.config.mjs

@@ -1,84 +1,108 @@
 // @ts-check
-import { defineConfig } from "astro/config";
-import starlight from "@astrojs/starlight";
-import remarkMath from "remark-math";
-import rehypeKatex from "rehype-katex";
+// The shared max-models docs setup (@max-models/starlight-theme). The site lives in astro_docs/
+// rather than docs/, hence the editLink override. The tutorial pages are converted from the
+// notebooks in tutorials/ by starlight-notebooks, the API page by scripts/generate_api_docs.py.
+import { defineDocs } from '@max-models/starlight-theme';
 
-// https://astro.build/config
-export default defineConfig({
-  site: "https://max-models.github.io/tikzfigure",
-  base: "/tikzfigure",
-  markdown: {
-    remarkPlugins: [remarkMath],
-    rehypePlugins: [rehypeKatex],
-  },
-  integrations: [
-    starlight({
-      title: "tikzfigure",
-      logo: { src: "./src/assets/logo.png", replacesTitle: true },
-      customCss: ["katex/dist/katex.min.css"],
-      social: [
-        {
-          icon: "github",
-          label: "GitHub",
-          href: "https://github.com/max-models/tikzfigure",
-        },
-      ],
-      sidebar: [
-        { label: "Home", slug: "" },
-        { label: "Installation", slug: "installation" },
-        {
-          label: "Fundamentals",
-          items: [
-            { label: "Getting Started", slug: "tutorials/tutorial_01_getting_started" },
-            { label: "Styling", slug: "tutorials/tutorial_02_styling" },
-            { label: "Saving and Exporting", slug: "tutorials/tutorial_16_saving_and_exporting" },
-          ],
-        },
-        {
-          label: "Drawing",
-          items: [
-            { label: "Paths", slug: "tutorials/tutorial_03_paths" },
-            { label: "TikZ Primitives", slug: "tutorials/tutorial_04_primitives" },
-            { label: "Layers", slug: "tutorials/tutorial_05_layers" },
-            { label: "Loops", slug: "tutorials/tutorial_06_loops" },
-            { label: "Coordinates and Midpoints", slug: "tutorials/tutorial_07_coordinates_and_midpoints" },
-          ],
-        },
-        {
-          label: "2D Plots",
-          items: [
-            { label: "Basics", slug: "tutorials/tutorial_11_2d_plots_basics" },
-            { label: "Styling", slug: "tutorials/tutorial_12_2d_plots_styling" },
-            { label: "Functions", slug: "tutorials/tutorial_13_2d_plots_functions" },
-            { label: "Subfigures and Grids", slug: "tutorials/tutorial_14_subfigures" },
-            { label: "Mixed Subfigures", slug: "tutorials/tutorial_15_mixed_subfigures" },
-          ],
-        },
-        {
-          label: "Advanced",
-          items: [
-            { label: "3D Figures", slug: "tutorials/tutorial_08_3d_figures" },
-            { label: "Raw TikZ", slug: "tutorials/tutorial_09_raw_tikz" },
-            { label: "Math Expressions", slug: "tutorials/tutorial_10_math_expressions" },
-            { label: "Tokamak X-Point", slug: "tutorials/tutorial_25_parametric_tikz_plots" },
-            { label: "Figure Configuration", slug: "tutorials/tutorial_17_figure_configuration" },
-            { label: "Shading and Patterns", slug: "tutorials/tutorial_18_shading_and_patterns" },
-            { label: "Opacity", slug: "tutorials/tutorial_19_opacity_and_transparency" },
-            { label: "Decorations", slug: "tutorials/tutorial_20_decorations" },
-            { label: "Advanced Styling", slug: "tutorials/tutorial_21_advanced_styling" },
-            { label: "Gantt Charts", slug: "tutorials/tutorial_26_gantt" },
-          ],
-        },
-        {
-          label: "Showcases",
-          items: [
-            { label: "Calendar", slug: "tutorials/tutorial_22_calendar" },
-          ],
-        },
-        { label: "API Reference", slug: "api" },
-        { label: "Interactive Editor", slug: "editor" },
-      ],
-    }),
-  ],
+export default defineDocs({
+	repo: 'tikzfigure',
+	title: 'tikzfigure',
+	description: 'A Python library to generate readable TikZ figures.',
+	nav: [
+		{ label: 'Installation', link: '/installation/' },
+		{ label: 'Tutorials', link: '/tutorials/tutorial-01-getting-started/', section: '/tutorials/' },
+		{ label: 'API Reference', link: '/api/' },
+		{ label: 'Interactive Editor', link: '/editor/' },
+	],
+	sidebar: [
+		{ label: 'Home', slug: '' },
+		{ label: 'Installation', slug: 'installation' },
+		{
+			label: 'Fundamentals',
+			items: [
+				{ label: 'Getting Started', slug: 'tutorials/tutorial-01-getting-started' },
+				{ label: 'Styling', slug: 'tutorials/tutorial-02-styling' },
+				{ label: 'Saving and Exporting', slug: 'tutorials/tutorial-16-saving-and-exporting' },
+			],
+		},
+		{
+			label: 'Drawing',
+			items: [
+				{ label: 'Paths', slug: 'tutorials/tutorial-03-paths' },
+				{ label: 'TikZ Primitives', slug: 'tutorials/tutorial-04-primitives' },
+				{ label: 'Layers', slug: 'tutorials/tutorial-05-layers' },
+				{ label: 'Loops', slug: 'tutorials/tutorial-06-loops' },
+				{ label: 'Coordinates and Midpoints', slug: 'tutorials/tutorial-07-coordinates-and-midpoints' },
+			],
+		},
+		{
+			label: '2D Plots',
+			items: [
+				{ label: 'Basics', slug: 'tutorials/tutorial-11-2d-plots-basics' },
+				{ label: 'Styling', slug: 'tutorials/tutorial-12-2d-plots-styling' },
+				{ label: 'Functions', slug: 'tutorials/tutorial-13-2d-plots-functions' },
+				{ label: 'Subfigures and Grids', slug: 'tutorials/tutorial-14-subfigures' },
+				{ label: 'Mixed Subfigures', slug: 'tutorials/tutorial-15-mixed-subfigures' },
+			],
+		},
+		{
+			label: 'Advanced',
+			items: [
+				{ label: '3D Figures', slug: 'tutorials/tutorial-08-3d-figures' },
+				{ label: 'Raw TikZ', slug: 'tutorials/tutorial-09-raw-tikz' },
+				{ label: 'Math Expressions', slug: 'tutorials/tutorial-10-math-expressions' },
+				{ label: 'Tokamak X-Point', slug: 'tutorials/tutorial-25-parametric-tikz-plots' },
+				{ label: 'Figure Configuration', slug: 'tutorials/tutorial-17-figure-configuration' },
+				{ label: 'Shading and Patterns', slug: 'tutorials/tutorial-18-shading-and-patterns' },
+				{ label: 'Opacity', slug: 'tutorials/tutorial-19-opacity-and-transparency' },
+				{ label: 'Decorations', slug: 'tutorials/tutorial-20-decorations' },
+				{ label: 'Advanced Styling', slug: 'tutorials/tutorial-21-advanced-styling' },
+				{ label: 'Gantt Charts', slug: 'tutorials/tutorial-26-gantt' },
+			],
+		},
+		{
+			label: 'Showcases',
+			items: [{ label: 'Calendar', slug: 'tutorials/tutorial-22-calendar' }],
+		},
+		{ label: 'API Reference', slug: 'api' },
+		{ label: 'Interactive Editor', slug: 'editor' },
+	],
+	astro: {
+		// the pages had the notebooks' file names before (Quarto)
+		redirects: {
+			'/tutorials/tutorial_01_getting_started/': '/tutorials/tutorial-01-getting-started/',
+			'/tutorials/tutorial_02_styling/': '/tutorials/tutorial-02-styling/',
+			'/tutorials/tutorial_03_paths/': '/tutorials/tutorial-03-paths/',
+			'/tutorials/tutorial_04_primitives/': '/tutorials/tutorial-04-primitives/',
+			'/tutorials/tutorial_05_layers/': '/tutorials/tutorial-05-layers/',
+			'/tutorials/tutorial_06_loops/': '/tutorials/tutorial-06-loops/',
+			'/tutorials/tutorial_07_coordinates_and_midpoints/': '/tutorials/tutorial-07-coordinates-and-midpoints/',
+			'/tutorials/tutorial_08_3d_figures/': '/tutorials/tutorial-08-3d-figures/',
+			'/tutorials/tutorial_09_raw_tikz/': '/tutorials/tutorial-09-raw-tikz/',
+			'/tutorials/tutorial_10_math_expressions/': '/tutorials/tutorial-10-math-expressions/',
+			'/tutorials/tutorial_11_2d_plots_basics/': '/tutorials/tutorial-11-2d-plots-basics/',
+			'/tutorials/tutorial_11_jupyter_magic/': '/tutorials/tutorial-11-jupyter-magic/',
+			'/tutorials/tutorial_12_2d_plots_styling/': '/tutorials/tutorial-12-2d-plots-styling/',
+			'/tutorials/tutorial_13_2d_plots_functions/': '/tutorials/tutorial-13-2d-plots-functions/',
+			'/tutorials/tutorial_14_subfigures/': '/tutorials/tutorial-14-subfigures/',
+			'/tutorials/tutorial_15_mixed_subfigures/': '/tutorials/tutorial-15-mixed-subfigures/',
+			'/tutorials/tutorial_16_images_legends_and_ticks/': '/tutorials/tutorial-16-images-legends-and-ticks/',
+			'/tutorials/tutorial_16_saving_and_exporting/': '/tutorials/tutorial-16-saving-and-exporting/',
+			'/tutorials/tutorial_17_figure_configuration/': '/tutorials/tutorial-17-figure-configuration/',
+			'/tutorials/tutorial_18_shading_and_patterns/': '/tutorials/tutorial-18-shading-and-patterns/',
+			'/tutorials/tutorial_19_opacity_and_transparency/': '/tutorials/tutorial-19-opacity-and-transparency/',
+			'/tutorials/tutorial_20_decorations/': '/tutorials/tutorial-20-decorations/',
+			'/tutorials/tutorial_21_advanced_styling/': '/tutorials/tutorial-21-advanced-styling/',
+			'/tutorials/tutorial_22_calendar/': '/tutorials/tutorial-22-calendar/',
+			'/tutorials/tutorial_23_karl_students/': '/tutorials/tutorial-23-karl-students/',
+			'/tutorials/tutorial_24_spy_library/': '/tutorials/tutorial-24-spy-library/',
+			'/tutorials/tutorial_25_parametric_tikz_plots/': '/tutorials/tutorial-25-parametric-tikz-plots/',
+			'/tutorials/tutorial_26_gantt/': '/tutorials/tutorial-26-gantt/',
+			'/tutorials/tutorial_27_parsing_tikz/': '/tutorials/tutorial-27-parsing-tikz/',
+		},
+	},
+	starlight: {
+		logo: { src: './src/assets/logo.png', replacesTitle: true },
+		editLink: { baseUrl: 'https://github.com/max-models/tikzfigure/edit/devel/astro_docs/' },
+	},
 });