From f44497c1bbe11f1bf0b4564be7d4ff242109a6a6 Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Wed, 30 Sep 2026 14:04:31 -0400 Subject: [PATCH 1/7] Add doc requirements and build location --- doc/requirements.txt | 6 ++++++ doc/source/conf.py | 5 ++++- 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 doc/requirements.txt diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..fb15ff1e9a --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,6 @@ +# Python packages needed to build the documentation. These are the exact +# versions the documentation workflow (.github/workflows/documentation.yml) +# uses to build and publish https://edgcpp.org/compiler/. Sphinx 9.1 +# requires Python 3.12 or newer. +Sphinx==9.1.0 +shibuya==2026.7.12 diff --git a/doc/source/conf.py b/doc/source/conf.py index 1c304bb78c..e31f46b8ab 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -29,7 +29,7 @@ 'Ellen Herrick', 'Nina Ranns', 'Caleb Sunstrum', - 'Wyatt Childers' + 'Wyatt Childers', 'Christof Meerwald' ]) @@ -67,6 +67,9 @@ # html_theme = 'shibuya' +# Where the published documentation lives; used for canonical links. +html_baseurl = 'https://edgcpp.org/compiler/' + html_theme_options = { 'light_logo': '_static/doc-logo-light.png', 'dark_logo': '_static/doc-logo-dark.png' From bd833c9d28f7e59a7c872fefe08b3cc55e0bba19 Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Wed, 30 Sep 2026 14:04:43 -0400 Subject: [PATCH 2/7] Add documentation workflow to CI --- .github/workflows/documentation.yml | 87 +++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000000..50748cc7ce --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,87 @@ +# Part of the EDG Compiler Project, under the Apache License v2.0 with LLVM +# Exceptions. +# See https://edgcpp.org/LICENSE.txt for license information. +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +# +# Build the Sphinx documentation in doc/ with warnings treated as errors. +# Pushes to main in edgcpp/compiler also publish the HTML to GitHub Pages, +# which serves it at https://edgcpp.org/compiler/ (the org site's custom +# domain applies to every project site in the edgcpp org). +# +# This requires the repository's Pages source to be set to "GitHub Actions" +# (Settings > Pages > Build and deployment > Source). + +name: Documentation + +on: + push: + branches: + - main + paths: + - 'doc/**' + - '.github/workflows/documentation.yml' + pull_request: + paths: + - 'doc/**' + - '.github/workflows/documentation.yml' + workflow_dispatch: + +permissions: + contents: read + +# Supersede queued runs for the same ref, but let an in-progress deployment +# to Pages finish rather than cancelling it partway through. +concurrency: + group: documentation-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + build: + name: Build HTML documentation + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Check out repository + uses: actions/checkout@v7 + + - name: Set up Python + uses: actions/setup-python@v7 + with: + python-version: '3.14' + cache: pip + cache-dependency-path: doc/requirements.txt + + - name: Install Sphinx + run: python -m pip install -r doc/requirements.txt + + - name: Build HTML + run: make -C doc html SPHINXOPTS="-W --keep-going" + + - name: Upload Pages artifact + if: > + github.repository == 'edgcpp/compiler' && + github.event_name != 'pull_request' && + github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v5 + with: + path: doc/build/html + + deploy: + name: Deploy to GitHub Pages + needs: build + if: > + github.repository == 'edgcpp/compiler' && + github.event_name != 'pull_request' && + github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy documentation + id: deployment + uses: actions/deploy-pages@v5 From 244219e281b9d622a766e955bf02d9296b0598ef Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Wed, 30 Sep 2026 14:05:04 -0400 Subject: [PATCH 3/7] Update READMEs with canonical URL and build instructions --- README.md | 2 +- doc/README.md | 24 +++++++++++++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e4c7356543..240b7db604 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ development tools. ## Documentation -See the documentation on: https://edgcpp.org/doc/. +See the documentation on: https://edgcpp.org/compiler/. > [!NOTE] > diff --git a/doc/README.md b/doc/README.md index 5544972db9..8b925eedd9 100644 --- a/doc/README.md +++ b/doc/README.md @@ -15,18 +15,40 @@ If `pip3` is not an alias for Python 3's PIP, use: pip install -U Sphinx shibuya ``` +To use the exact versions that the published documentation is built with +(requires Python 3.12 or newer): + +``` +pip3 install -r doc/requirements.txt +``` + ## Make HTML To make an HTML version of the documentation, after Sphinx is installed: ``` -cd doc-sphinx +cd doc make html ``` These files can then be viewed in the browser by opening `build/html/index.html`. +To check for warnings the same way CI does, which fails on any warning: + +``` +make html SPHINXOPTS="-W --keep-going" +``` + +## Publishing + +The documentation is published to https://edgcpp.org/compiler/ by the +[Documentation workflow](../.github/workflows/documentation.yml). It builds +the HTML for every pull request that touches `doc/`, and on each push to +`main` that touches `doc/` it deploys the result to GitHub Pages. It can also +be run by hand from the Actions tab ("Run workflow"). Nothing needs to be +committed to publish; the built HTML is never checked in. + ## Useful Links: - [reStructuredText Basics](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) From 237c9d2024283e5e39e0b322a2995d2f4dabc7aa Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Wed, 30 Sep 2026 14:05:21 -0400 Subject: [PATCH 4/7] Add auto generated files to gitignore --- .gitignore | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.gitignore b/.gitignore index 2f14c5278c..4c0397994d 100644 --- a/.gitignore +++ b/.gitignore @@ -53,9 +53,16 @@ bin CMakeFiles/ CMakeCache.txt compile_commands.json +cmake/macro-conf/*.cmakedef # clangd cache files .cache/ # VS-created items to ignore: .vs/ + +# CLion-created items to ignore: +.idea/ + +# AI tooling items to ignore: +CLAUDE.md From 635de70fb9116d8149e0a511609766c4679b9f62 Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Wed, 30 Sep 2026 15:01:56 -0400 Subject: [PATCH 5/7] /doc/ hosts the latest tagged release and /dev/doc now tracks main --- .github/workflows/documentation.yml | 57 +++++++++++++---------------- README.md | 3 +- doc/README.md | 25 +++++++++---- doc/requirements.txt | 5 +-- doc/source/conf.py | 3 -- 5 files changed, 47 insertions(+), 46 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 50748cc7ce..27ca445462 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -3,13 +3,16 @@ # See https://edgcpp.org/LICENSE.txt for license information. # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception # -# Build the Sphinx documentation in doc/ with warnings treated as errors. -# Pushes to main in edgcpp/compiler also publish the HTML to GitHub Pages, -# which serves it at https://edgcpp.org/compiler/ (the org site's custom -# domain applies to every project site in the edgcpp org). +# Build the Sphinx documentation in doc/ with warnings treated as errors, so +# documentation changes stay publishable. # -# This requires the repository's Pages source to be set to "GitHub Actions" -# (Settings > Pages > Build and deployment > Source). +# The documentation is published by the edgcpp/edgcpp.github.io site +# workflow, not from here: it builds the release tag into +# https://edgcpp.org/doc/ and main into https://edgcpp.org/dev/doc/. After a +# push to main passes the build, this asks that workflow to run so the +# development documentation is updated. That needs the SITE_DISPATCH_TOKEN +# secret: a fine-grained token for edgcpp/edgcpp.github.io only, with +# "Actions: Read and write" permission. name: Documentation @@ -29,11 +32,9 @@ on: permissions: contents: read -# Supersede queued runs for the same ref, but let an in-progress deployment -# to Pages finish rather than cancelling it partway through. concurrency: group: documentation-${{ github.ref }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + cancel-in-progress: true jobs: build: @@ -54,34 +55,28 @@ jobs: - name: Install Sphinx run: python -m pip install -r doc/requirements.txt + # The published site uses the dirhtml builder, so check that one. - name: Build HTML - run: make -C doc html SPHINXOPTS="-W --keep-going" + run: make -C doc dirhtml SPHINXOPTS="-W --keep-going" - - name: Upload Pages artifact - if: > - github.repository == 'edgcpp/compiler' && - github.event_name != 'pull_request' && - github.ref == 'refs/heads/main' - uses: actions/upload-pages-artifact@v5 - with: - path: doc/build/html - - deploy: - name: Deploy to GitHub Pages + publish-dev: + name: Publish development documentation needs: build if: > github.repository == 'edgcpp/compiler' && github.event_name != 'pull_request' && github.ref == 'refs/heads/main' runs-on: ubuntu-latest - timeout-minutes: 10 - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} + timeout-minutes: 5 steps: - - name: Deploy documentation - id: deployment - uses: actions/deploy-pages@v5 + - name: Trigger the edgcpp.org site build + env: + GH_TOKEN: ${{ secrets.SITE_DISPATCH_TOKEN }} + run: | + if [ -z "$GH_TOKEN" ]; then + echo "::warning::SITE_DISPATCH_TOKEN is not set, so" \ + "https://edgcpp.org/dev/doc/ was not updated." + exit 0 + fi + gh workflow run build_and_deploy.yml \ + --repo edgcpp/edgcpp.github.io --ref develop diff --git a/README.md b/README.md index 240b7db604..f6c332d599 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,8 @@ development tools. ## Documentation -See the documentation on: https://edgcpp.org/compiler/. +See the documentation on: https://edgcpp.org/doc/. Documentation for the +current development branch (`main`) is on: https://edgcpp.org/dev/doc/. > [!NOTE] > diff --git a/doc/README.md b/doc/README.md index 8b925eedd9..b012be957f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -15,8 +15,8 @@ If `pip3` is not an alias for Python 3's PIP, use: pip install -U Sphinx shibuya ``` -To use the exact versions that the published documentation is built with -(requires Python 3.12 or newer): +To use the exact versions that CI checks the documentation with (requires +Python 3.12 or newer): ``` pip3 install -r doc/requirements.txt @@ -42,12 +42,21 @@ make html SPHINXOPTS="-W --keep-going" ## Publishing -The documentation is published to https://edgcpp.org/compiler/ by the -[Documentation workflow](../.github/workflows/documentation.yml). It builds -the HTML for every pull request that touches `doc/`, and on each push to -`main` that touches `doc/` it deploys the result to GitHub Pages. It can also -be run by hand from the Actions tab ("Run workflow"). Nothing needs to be -committed to publish; the built HTML is never checked in. +The [website repository](https://github.com/edgcpp/edgcpp.github.io) builds +this documentation with `make dirhtml` and publishes two copies of it: + +- https://edgcpp.org/doc/ is the release documentation, built from the tag + named by `COMPILER_DOC_REF` in the website's + `.github/workflows/build_and_deploy.yml`. Bump that to publish a newer + release's documentation. +- https://edgcpp.org/dev/doc/ is the development documentation, built from + `main`. + +In this repository, the +[Documentation workflow](../.github/workflows/documentation.yml) checks that +the documentation builds without warnings on every pull request and push to +`main` that touches `doc/`. When such a push to `main` passes, it triggers +the website's workflow, which updates https://edgcpp.org/dev/doc/. ## Useful Links: diff --git a/doc/requirements.txt b/doc/requirements.txt index fb15ff1e9a..87e3278105 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,5 @@ # Python packages needed to build the documentation. These are the exact -# versions the documentation workflow (.github/workflows/documentation.yml) -# uses to build and publish https://edgcpp.org/compiler/. Sphinx 9.1 -# requires Python 3.12 or newer. +# versions the documentation check (.github/workflows/documentation.yml) +# builds with. Sphinx 9.1 requires Python 3.12 or newer. Sphinx==9.1.0 shibuya==2026.7.12 diff --git a/doc/source/conf.py b/doc/source/conf.py index e31f46b8ab..76ab80f065 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -67,9 +67,6 @@ # html_theme = 'shibuya' -# Where the published documentation lives; used for canonical links. -html_baseurl = 'https://edgcpp.org/compiler/' - html_theme_options = { 'light_logo': '_static/doc-logo-light.png', 'dark_logo': '_static/doc-logo-dark.png' From 62a2f593c1f99756c1fd439083866830e5589abe Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Thu, 1 Oct 2026 09:32:45 -0400 Subject: [PATCH 6/7] Remove --keep-going flag --- .github/workflows/documentation.yml | 2 +- doc/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 27ca445462..2a9cb7db71 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -57,7 +57,7 @@ jobs: # The published site uses the dirhtml builder, so check that one. - name: Build HTML - run: make -C doc dirhtml SPHINXOPTS="-W --keep-going" + run: make -C doc dirhtml SPHINXOPTS="-W" publish-dev: name: Publish development documentation diff --git a/doc/README.md b/doc/README.md index b012be957f..8c98d74584 100644 --- a/doc/README.md +++ b/doc/README.md @@ -37,7 +37,7 @@ These files can then be viewed in the browser by opening To check for warnings the same way CI does, which fails on any warning: ``` -make html SPHINXOPTS="-W --keep-going" +make html SPHINXOPTS="-W" ``` ## Publishing From bab3b2b3a69717829bbd0606ea7cabbed6534d19 Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Thu, 1 Oct 2026 09:37:42 -0400 Subject: [PATCH 7/7] Update docker/sphinx-env --- dev_tools/docker/sphinx-env/.gitignore | 1 + dev_tools/docker/sphinx-env/Dockerfile | 3 +++ dev_tools/docker/sphinx-env/prebuild.py | 24 +++++++++++++++++++ .../setup-scripts/install-pip-packages.sh | 4 ++-- .../setup-scripts/install-software.sh | 4 ++++ 5 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 dev_tools/docker/sphinx-env/.gitignore create mode 100644 dev_tools/docker/sphinx-env/prebuild.py diff --git a/dev_tools/docker/sphinx-env/.gitignore b/dev_tools/docker/sphinx-env/.gitignore new file mode 100644 index 0000000000..4414fc1e28 --- /dev/null +++ b/dev_tools/docker/sphinx-env/.gitignore @@ -0,0 +1 @@ +requirements.txt diff --git a/dev_tools/docker/sphinx-env/Dockerfile b/dev_tools/docker/sphinx-env/Dockerfile index b8ee3dfa59..b3d9467621 100644 --- a/dev_tools/docker/sphinx-env/Dockerfile +++ b/dev_tools/docker/sphinx-env/Dockerfile @@ -15,6 +15,9 @@ RUN mkdir /edg && \ mkdir /edg/user-script/pip-packages/ COPY setup-scripts/* /edg/setup-scripts/ +# Copy in doc/requirements.txt (see prebuild.py) for the pip packages. +COPY requirements.txt /edg/setup-scripts/requirements.txt + # Execute root based setup scripts. RUN /edg/setup-scripts/run-all.sh diff --git a/dev_tools/docker/sphinx-env/prebuild.py b/dev_tools/docker/sphinx-env/prebuild.py new file mode 100644 index 0000000000..229f3c365e --- /dev/null +++ b/dev_tools/docker/sphinx-env/prebuild.py @@ -0,0 +1,24 @@ +# Part of the EDG Compiler Project, under the Apache License v2.0 with LLVM +# Exceptions. +# See https://edgcpp.org/LICENSE.txt for license information. +# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception + +# This script is executed by build-edg-env before creation of the Docker image +# to copy in the documentation's requirements.txt file. + +import os +import shutil + +import edgtools + +from pathlib import Path + +def copy_requirements_file() -> None: + '''Copy doc/requirements.txt for use by the Dockerfile.''' + doc_dir = edgtools.get_tools_dir().parent / 'doc' + shutil.copy(doc_dir / 'requirements.txt', Path(os.getcwd())) + +def main() -> None: + copy_requirements_file() + +main() diff --git a/dev_tools/docker/sphinx-env/setup-scripts/install-pip-packages.sh b/dev_tools/docker/sphinx-env/setup-scripts/install-pip-packages.sh index 00cf99d197..01ec9640db 100755 --- a/dev_tools/docker/sphinx-env/setup-scripts/install-pip-packages.sh +++ b/dev_tools/docker/sphinx-env/setup-scripts/install-pip-packages.sh @@ -5,5 +5,5 @@ # See https://edgcpp.org/LICENSE.txt for license information. # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception -# Install Sphinx using pip -pip install -U Sphinx shibuya +# Install the documentation's pinned packages (doc/requirements.txt) using pip +pip install -r /edg/setup-scripts/requirements.txt diff --git a/dev_tools/docker/sphinx-env/setup-scripts/install-software.sh b/dev_tools/docker/sphinx-env/setup-scripts/install-software.sh index 36f445d373..b4151dd0e0 100755 --- a/dev_tools/docker/sphinx-env/setup-scripts/install-software.sh +++ b/dev_tools/docker/sphinx-env/setup-scripts/install-software.sh @@ -20,6 +20,10 @@ packages+=( "texlive-collection-latexextra" ) +# Add required packages for checkout to function (in CI, see +# .github/workflows/documentation.yml) +packages+=("git" "nodejs") + # Add useful linux commands packages+=("util-linux") # kill, runuser