diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000000..2a9cb7db71 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,82 @@ +# 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 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 + 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 + + # 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 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 diff --git a/README.md b/README.md index e4c7356543..f6c332d599 100644 --- a/README.md +++ b/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] > 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 diff --git a/doc/README.md b/doc/README.md index 5544972db9..8c98d74584 100644 --- a/doc/README.md +++ b/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) diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..87e3278105 --- /dev/null +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py index 1c304bb78c..76ab80f065 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' ])