Swap docs toolchain from MyST to Quarto

.github/workflows/pr_docs_changes.yaml

@@ -18,10 +18,7 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 18.x
-      - name: Install MyST
-        run: npm install -g mystmd
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
       - name: Test documentation builds
-        run: cd docs && myst build --html
+        run: quarto render docs

Makefile

@@ -1,15 +1,12 @@
 .PHONY: docs docs-serve
 
-MYSTMD_VERSION ?= 1.8.3
-MYST_CMD = npx --yes mystmd@$(MYSTMD_VERSION)
-
 all: build-package
 
 docs:
-	cd docs && $(MYST_CMD) build --html
+	quarto render docs
 
 docs-serve:
-	cd docs && $(MYST_CMD) start
+	quarto preview docs
 
 install:
 	uv pip install -e .[dev]

README.md

@@ -110,7 +110,7 @@ uv pip install -e .[dev]        # install with dev dependencies (pytest, ruff, m
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs             # build static Quarto HTML docs
 make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```

docs/.gitignore

@@ -1,2 +1,5 @@
-# MyST build outputs
-_build
+# Quarto build outputs
+_site
+_freeze
+/.quarto/
+**/*.quarto_ipynb

docs/_quarto.yml

@@ -0,0 +1,48 @@
+project:
+  type: website
+  output-dir: _site
+  preview:
+    port: 8080
+
+website:
+  title: "PolicyEngine"
+  description: "Tax-benefit microsimulation for Python."
+  repo-url: https://github.com/PolicyEngine/policyengine.py
+  repo-actions: [edit, issue]
+  page-navigation: true
+  navbar:
+    left:
+      - href: index.md
+        text: Overview
+      - core-concepts.md
+      - economic-impact-analysis.md
+      - country-models-us.md
+      - country-models-uk.md
+      - examples.md
+      - dev.md
+  sidebar:
+    style: "floating"
+    collapse-level: 2
+    contents:
+      - index.md
+      - core-concepts.md
+      - economic-impact-analysis.md
+      - advanced-outputs.md
+      - regions-and-scoping.md
+      - country-models-uk.md
+      - country-models-us.md
+      - examples.md
+      - visualisation.md
+      - release-bundles.md
+      - dev.md
+
+format:
+  html:
+    theme: [cosmo]
+    toc: true
+    toc-depth: 3
+    code-copy: true
+    code-overflow: wrap
+    highlight-style: github
+    anchor-sections: true
+    link-external-newwindow: true

docs/dev.md

@@ -23,7 +23,7 @@ dependencies used in CI (pytest, ruff, mypy, towncrier).
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs             # build static Quarto HTML docs
 make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```

docs/examples.md

@@ -6,62 +6,54 @@ Complete working scripts demonstrating common workflows. Each script can be run
 
 The canonical workflow for comparing a baseline and reform simulation, using both `economic_impact_analysis()` and `ChangeAggregate`.
 
-```{literalinclude} ../examples/us_budgetary_impact.py
-:language: python
+```{.python include="../examples/us_budgetary_impact.py"}
 ```
 
 ## UK policy reform analysis
 
 Applying parametric reforms, comparing baseline and reform with `ChangeAggregate`, analysing winners and losers by income decile, and visualising results with Plotly.
 
-```{literalinclude} ../examples/policy_change_uk.py
-:language: python
+```{.python include="../examples/policy_change_uk.py"}
 ```
 
 ## UK income bands
 
 Calculating net income and tax by income decile using representative microdata and `Aggregate` with quantile filters.
 
-```{literalinclude} ../examples/income_bands_uk.py
-:language: python
+```{.python include="../examples/income_bands_uk.py"}
 ```
 
 ## US income distribution
 
 Loading enhanced CPS microdata, running a full microsimulation, and calculating statistics within income deciles.
 
-```{literalinclude} ../examples/income_distribution_us.py
-:language: python
+```{.python include="../examples/income_distribution_us.py"}
 ```
 
 ## UK employment income variation
 
 Creating a custom dataset with varied employment income, running a single simulation, and visualising benefit phase-outs.
 
-```{literalinclude} ../examples/employment_income_variation_uk.py
-:language: python
+```{.python include="../examples/employment_income_variation_uk.py"}
 ```
 
 ## US employment income variation
 
 Same approach as the UK version, varying employment income from $0 to $200k and plotting household net income.
 
-```{literalinclude} ../examples/employment_income_variation_us.py
-:language: python
+```{.python include="../examples/employment_income_variation_us.py"}
 ```
 
 ## Household calculation
 
 Using `pe.uk.calculate_household()` and `pe.us.calculate_household()` to compute taxes and benefits for individual custom households with flat keyword arguments and dot-access result objects.
 
-```{literalinclude} ../examples/household_impact_example.py
-:language: python
+```{.python include="../examples/household_impact_example.py"}
 ```
 
 ## Simulation performance
 
 Benchmarking how `simulation.run()` scales with dataset size.
 
-```{literalinclude} ../examples/speedtest_us_simulation.py
-:language: python
+```{.python include="../examples/speedtest_us_simulation.py"}
 ```