Add GitHub workflow support for updating a version of the documention based on the latest development activity []

Author: mborland

.github/workflows/documentation.yml

@@ -0,0 +1,79 @@
+# 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, so
+# documentation changes stay publishable.
+#
+# The build runs in the edgcpp/sphinx-env image, which the site workflow
+# described below also builds the published documentation with.  That image
+# installs the packages pinned in doc/requirements.txt, so after changing
+# them, rebuild it with build-edg-env sphinx-env and push it to Docker Hub.
+#
+# 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
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'doc/**'
+      - '.github/workflows/documentation.yml'
+  pull_request:
+    paths:
+      - 'doc/**'
+      - '.github/workflows/documentation.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build HTML documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    container:
+      image: docker.io/edgcpp/sphinx-env:latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      # The published site uses the dirhtml builder, so check that one.
+      - name: Build HTML
+        run: make -C doc dirhtml SPHINXOPTS="-W"
+
+  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: 5
+    steps:
+      - 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

.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

README.md

@@ -22,7 +22,8 @@ development tools.
 
 ## Documentation
 
-See the documentation on: https://edgcpp.org/doc/.
+See the documentation on: https://edgcpp.org/doc/.  Documentation for the
+current development branch (`main`) is on: https://edgcpp.org/dev/doc/.
 
 > [!NOTE]
 >

dev_tools/docker/sphinx-env/.gitignore

@@ -0,0 +1 @@
+requirements.txt

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
 

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()

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

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
 

doc/README.md

@@ -15,18 +15,49 @@ If `pip3` is not an alias for Python 3's PIP, use:
 pip install -U Sphinx shibuya
 ```
 
+To use the exact versions that CI checks the documentation 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"
+```
+
+## Publishing
+
+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:
 
 - [reStructuredText Basics](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)

doc/requirements.txt

@@ -0,0 +1,5 @@
+# Python packages needed to build the documentation.  These are the exact
+# 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