From 1169c8d41e62984433302edddcfaf150b90e083e Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:25:54 +0100 Subject: [PATCH 1/8] Fix Jupyter Book deployment to GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs.yaml workflow to build and deploy Jupyter Book using myst build - Fix branch reference in _config.yml from master to main - Configure GitHub Pages deployment with proper permissions Fixes #193 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/workflows/docs.yaml | 58 +++++++++++++++++++++++++++++++++++++ changelog_entry.yaml | 4 +++ docs/_config.yml | 2 +- 3 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 000000000..effd7216f --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,58 @@ +name: Deploy Jupyter Book + +on: + push: + branches: + - main + paths: + - "docs/**" + - ".github/workflows/docs.yaml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.13" + + - name: Install uv + uses: astral-sh/setup-uv@v5 + + - name: Install dependencies + run: | + uv pip install -e ".[dev]" --system + uv pip install jupyter-book myst-nb --system + + - name: Build book + run: myst build docs --html + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/changelog_entry.yaml b/changelog_entry.yaml index e69de29bb..74946ecb5 100644 --- a/changelog_entry.yaml +++ b/changelog_entry.yaml @@ -0,0 +1,4 @@ +- bump: patch + changes: + fixed: + - Jupyter Book deployment to GitHub Pages by adding docs workflow and fixing branch reference \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index 39d749820..d9b3934bc 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -10,7 +10,7 @@ execute: repository: url: https://github.com/policyengine/policyengine-uk-data - branch: master + branch: main path_to_book: docs sphinx: From a0e42d3e4fb531b99754f7c24f3d1432d290fc27 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:28:50 +0100 Subject: [PATCH 2/8] Build docs on PRs to catch errors before merge --- .github/workflows/docs.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index effd7216f..be8105db6 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -7,6 +7,10 @@ on: paths: - "docs/**" - ".github/workflows/docs.yaml" + pull_request: + paths: + - "docs/**" + - ".github/workflows/docs.yaml" workflow_dispatch: permissions: @@ -47,6 +51,7 @@ jobs: path: docs/_build/html deploy: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} From 22fed8f9804034c6ef41bfaa749b979de5454e29 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:30:20 +0100 Subject: [PATCH 3/8] Install mystmd CLI for building docs --- .github/workflows/docs.yaml | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index be8105db6..090ce3b73 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,10 +37,16 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v5 - - name: Install dependencies - run: | - uv pip install -e ".[dev]" --system - uv pip install jupyter-book myst-nb --system + - name: Install Node.js + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install MyST + run: npm install -g mystmd + + - name: Install Python dependencies + run: uv pip install -e ".[dev]" --system - name: Build book run: myst build docs --html From d8d3194019528f206982f95edce74e81b7772f3c Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:37:27 +0100 Subject: [PATCH 4/8] Use jupyter-book build instead of myst build --- .github/workflows/docs.yaml | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 090ce3b73..67e0f65ec 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,19 +37,11 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v5 - - name: Install Node.js - uses: actions/setup-node@v4 - with: - node-version: "22" - - - name: Install MyST - run: npm install -g mystmd - - name: Install Python dependencies run: uv pip install -e ".[dev]" --system - name: Build book - run: myst build docs --html + run: jupyter-book build docs - name: Upload artifact uses: actions/upload-pages-artifact@v3 From b82c54c881dc511e0d97cb95f885dfcab1a5f2cb Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:44:21 +0100 Subject: [PATCH 5/8] Upgrade to Jupyter Book 2.0 (MyST-based) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Migrated from Jupyter Book 1.x to 2.0 using MyST - Created myst.yml config (migrated from _config.yml and _toc.yml) - Updated workflow to install JB2.0 and run upgrade process - Old config files backed up as ._config.yml.bak and ._toc.yml.bak - Build command now: jupyter book build --html 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/workflows/docs.yaml | 14 +++++++++++--- changelog_entry.yaml | 4 +++- docs/{_config.yml => ._config.yml.bak} | 0 docs/{_toc.yml => ._toc.yml.bak} | 0 docs/myst.yml | 23 +++++++++++++++++++++++ 5 files changed, 37 insertions(+), 4 deletions(-) rename docs/{_config.yml => ._config.yml.bak} (100%) rename docs/{_toc.yml => ._toc.yml.bak} (100%) create mode 100644 docs/myst.yml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 67e0f65ec..bc40e64a0 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,11 +37,19 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v5 - - name: Install Python dependencies - run: uv pip install -e ".[dev]" --system + - name: Install Node.js + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Install Jupyter Book 2.0 + run: uv pip install --pre "jupyter-book==2.*" --system - name: Build book - run: jupyter-book build docs + run: | + cd docs + echo "Y" | jupyter book || true + jupyter book build --html - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/changelog_entry.yaml b/changelog_entry.yaml index 74946ecb5..dbb4c3b03 100644 --- a/changelog_entry.yaml +++ b/changelog_entry.yaml @@ -1,4 +1,6 @@ -- bump: patch +- bump: minor changes: + changed: + - Upgraded documentation to Jupyter Book 2.0 (MyST-based) fixed: - Jupyter Book deployment to GitHub Pages by adding docs workflow and fixing branch reference \ No newline at end of file diff --git a/docs/_config.yml b/docs/._config.yml.bak similarity index 100% rename from docs/_config.yml rename to docs/._config.yml.bak diff --git a/docs/_toc.yml b/docs/._toc.yml.bak similarity index 100% rename from docs/_toc.yml rename to docs/._toc.yml.bak diff --git a/docs/myst.yml b/docs/myst.yml new file mode 100644 index 000000000..0bf988b80 --- /dev/null +++ b/docs/myst.yml @@ -0,0 +1,23 @@ +version: 1 +project: + title: PolicyEngine UK data + authors: + - name: PolicyEngine + copyright: '2024' + github: policyengine/policyengine-uk-data + toc: + - file: intro.md + - file: methodology.ipynb + - file: validation/index.md + children: + - file: validation/national.ipynb + - file: validation/constituencies.ipynb + - file: validation/local_authorities.ipynb + - file: pension_contributions.ipynb + - file: constituency_methodology.ipynb + - file: LA_methodology.ipynb +site: + options: + logo: logo.png + folders: true + template: book-theme From 1b85d3a88d4883e561022a1709be81f50d70618d Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:51:03 +0100 Subject: [PATCH 6/8] Use myst build and gh-pages deployment like us-data MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Use myst build --html instead of jupyter book build - Set BASE_URL=/policyengine-uk-data for correct GitHub Pages paths - Create .nojekyll file in build output - Deploy to gh-pages branch using JamesIves/github-pages-deploy-action - Fix author name format in myst.yml to avoid warnings - Matches working policyengine-us-data deployment pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/workflows/docs.yaml | 39 +++++++++++++------------------------ docs/myst.yml | 4 +++- 2 files changed, 17 insertions(+), 26 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index bc40e64a0..fe9b123a1 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -14,16 +14,10 @@ on: workflow_dispatch: permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: "pages" - cancel-in-progress: false + contents: write jobs: - build: + build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout @@ -48,22 +42,17 @@ jobs: - name: Build book run: | cd docs - echo "Y" | jupyter book || true - jupyter book build --html - - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: docs/_build/html + rm -rf _build .jupyter_cache + myst clean || true + myst build --html + touch _build/html/.nojekyll + env: + BASE_URL: /policyengine-uk-data - deploy: - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: JamesIves/github-pages-deploy-action@v4 + with: + branch: gh-pages + folder: docs/_build/html + clean: true \ No newline at end of file diff --git a/docs/myst.yml b/docs/myst.yml index 0bf988b80..165211b47 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -2,7 +2,9 @@ version: 1 project: title: PolicyEngine UK data authors: - - name: PolicyEngine + - name: + given: PolicyEngine + family: Team copyright: '2024' github: policyengine/policyengine-uk-data toc: From df54373e21d1badaab8ec33d70ad0128fa1a925c Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:53:27 +0100 Subject: [PATCH 7/8] Install mystmd CLI via npm --- .github/workflows/docs.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index fe9b123a1..6e8fea8b3 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -36,8 +36,10 @@ jobs: with: node-version: "22" - - name: Install Jupyter Book 2.0 - run: uv pip install --pre "jupyter-book==2.*" --system + - name: Install Jupyter Book 2.0 and MyST + run: | + uv pip install --pre "jupyter-book==2.*" --system + npm install -g mystmd - name: Build book run: | From 0cb9c60df252c8401e7c9e318a3590f5f19bc338 Mon Sep 17 00:00:00 2001 From: Max Ghenis Date: Tue, 30 Sep 2025 14:54:47 +0100 Subject: [PATCH 8/8] Remove backup files from JB2.0 migration --- docs/._config.yml.bak | 24 ------------------------ docs/._toc.yml.bak | 12 ------------ 2 files changed, 36 deletions(-) delete mode 100644 docs/._config.yml.bak delete mode 100644 docs/._toc.yml.bak diff --git a/docs/._config.yml.bak b/docs/._config.yml.bak deleted file mode 100644 index d9b3934bc..000000000 --- a/docs/._config.yml.bak +++ /dev/null @@ -1,24 +0,0 @@ -title: PolicyEngine UK data -author: PolicyEngine -copyright: "2024" -logo: logo.png - -execute: - execute_notebooks: force - allow_errors: false - timeout: 600 - -repository: - url: https://github.com/policyengine/policyengine-uk-data - branch: main - path_to_book: docs - -sphinx: - config: - html_js_files: - - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.7/require.min.js - html_theme: furo - pygments_style: default - html_css_files: - - style.css - nb_remove_code_source: true \ No newline at end of file diff --git a/docs/._toc.yml.bak b/docs/._toc.yml.bak deleted file mode 100644 index 2e7dd86b2..000000000 --- a/docs/._toc.yml.bak +++ /dev/null @@ -1,12 +0,0 @@ -format: jb-book -root: intro -chapters: -- file: methodology.ipynb -- file: validation/index.md - sections: - - file: validation/national.ipynb - - file: validation/constituencies.ipynb - - file: validation/local_authorities.ipynb -- file: pension_contributions.ipynb -- file: constituency_methodology.ipynb -- file: LA_methodology.ipynb \ No newline at end of file