From 672dd5f8d7437d899fdfde20c31ee8d5c2c7a707 Mon Sep 17 00:00:00 2001 From: Samuel Debionne Date: Mon, 7 Sep 2026 13:04:49 +0200 Subject: [PATCH 1/2] ci: drop the custom MrDocs pin now that the segfault is fixed upstream MrDocs 2026.9.4 (official, non-prerelease release) fixes the segfault on GIL's CRTP-based headers that motivated pinning a personal build. The other bug that motivated it -- reference pages linking to private-member sub-pages MrDocs never emits -- is still open upstream (github.com/cppalliance/mrdocs/issues/1277). Oddly, GIL's specific repro from that issue passes cleanly against the tagged 2026.9.4 release binary itself, but fails again against the current `develop` tip (one commit newer) -- so this is unresolved/regressed, not fixed, regardless of that one data point. - docs-prerequisites / generate-doc: back to plain actions/setup-node@v4 + `bash build_antora.sh`, matching boostorg/url, redis and graph -- no cppalliance GitHub Action exists for MrDocs itself (it's resolved by the @cppalliance/antora-cpp-reference-extension npm package, not an Action), so this is the standard pattern other Boost libraries already use. - pixi.toml: drop the sdebionne/label/esrf-bcu channel and the mrdocs dependency; keeps Node + a C++ compiler for local `pixi run -e docs docs-build`, per request pixi itself stays for local dev. - build_antora.sh: drop the MRDOCS_ROOT/CONDA_PREFIX detection block. One deliberate remaining guard: local-playbook.yml keeps `failure_level: fatal` rather than `error`. Beyond #1277 itself, the extension's release selection always considers cppalliance/mrdocs' rolling `develop`/`master` tags (verified in its source: `allowMaster`/`allowDevelop` are hardcoded to `true` regardless of config, so a `version:` pin can't exclude them), so the exact MrDocs build used here isn't actually pinned and can vary from run to run. `fatal` keeps that class of cosmetic dangling-xref noise from hard-failing the build while still catching a real extraction failure. Co-Authored-By: Claude Sonnet 5 --- .github/actions/docs-prerequisites/action.yml | 4 ++-- .github/actions/generate-doc/action.yml | 4 +++- doc/build_antora.sh | 13 ------------- doc/local-playbook.yml | 17 ++++++++++------- doc/mrdocs.yml | 8 ++++---- pixi.lock | 9 --------- pixi.toml | 13 ++++++------- 7 files changed, 25 insertions(+), 43 deletions(-) diff --git a/.github/actions/docs-prerequisites/action.yml b/.github/actions/docs-prerequisites/action.yml index a75f83723d..c52a8fbfc2 100644 --- a/.github/actions/docs-prerequisites/action.yml +++ b/.github/actions/docs-prerequisites/action.yml @@ -3,6 +3,6 @@ description: 'Downloads all the necessary packages for building documentation' runs: using: composite steps: - - uses: prefix-dev/setup-pixi@v0.8.1 + - uses: actions/setup-node@v4 with: - environments: docs + node-version: 20 diff --git a/.github/actions/generate-doc/action.yml b/.github/actions/generate-doc/action.yml index 0badbdb11b..dff8544db2 100644 --- a/.github/actions/generate-doc/action.yml +++ b/.github/actions/generate-doc/action.yml @@ -11,7 +11,9 @@ runs: # BOOST_SRC_DIR (cross-library headers for MrDocs) comes from # ../boost-root. export BOOST_SRC_DIR="$(cd ../boost-root && pwd)" - pixi run -e docs docs-build + cd doc + bash build_antora.sh + cd .. chmod +x $GITHUB_WORKSPACE/.github/actions/generate-doc/docs-config.sh $GITHUB_WORKSPACE/.github/actions/generate-doc/docs-config.sh shell: bash diff --git a/doc/build_antora.sh b/doc/build_antora.sh index 6d9c8c4568..8fd11624d4 100644 --- a/doc/build_antora.sh +++ b/doc/build_antora.sh @@ -26,19 +26,6 @@ fi export BOOST_SRC_DIR="${BOOST_SRC_DIR:-$(realpath "$SCRIPT_DIR/../../..")}" echo "Using BOOST_SRC_DIR=$BOOST_SRC_DIR" -# Pin the @cppalliance/antora-cpp-reference-extension to a local MrDocs -# instead of it downloading the latest GitHub release, which as of this -# writing still segfaults on GIL's headers (upstream fix not released yet). -# When running under `pixi run -e docs`, CONDA_PREFIX/bin/mrdocs is the -# package from the sdebionne/label/esrf-bcu channel (see pixi.toml), which -# repackages the fixed dev build. Falls through to auto-download otherwise. -if [ -z "${MRDOCS_ROOT:-}" ] && [ -n "${CONDA_PREFIX:-}" ] && [ -x "$CONDA_PREFIX/bin/mrdocs" ]; then - export MRDOCS_ROOT="$CONDA_PREFIX" -fi -if [ -n "${MRDOCS_ROOT:-}" ]; then - echo "Using MRDOCS_ROOT=$MRDOCS_ROOT" -fi - echo "Generating the MrDocs compilation database..." # See mrdocs.yml / mrdocs-src/all.cpp: a single translation unit is enough # for MrDocs to extract the whole public API, and is far faster than trying diff --git a/doc/local-playbook.yml b/doc/local-playbook.yml index 768ac3499e..d5e92e275d 100644 --- a/doc/local-playbook.yml +++ b/doc/local-playbook.yml @@ -47,11 +47,14 @@ output: runtime: log: - # `fatal`, not `error`: some MrDocs-generated reference pages link to - # private-member sub-pages (e.g. packed_pixel's `_bitfield`) that MrDocs - # doesn't actually emit, regardless of extract-private -- a small, - # cosmetic upstream issue unrelated to this migration, logged as `error` - # by Antora. `failure_level` is a floor, not a ceiling: `error` messages - # still fail the build at `warn`. Once the MrDocs issue is fixed this - # should go back to `error`. + # `fatal`, not `error`: MrDocs still has an open bug where some generated + # reference pages link to private-member sub-pages it never actually + # emits (github.com/cppalliance/mrdocs/issues/1277). On top of that, + # @cppalliance/antora-cpp-reference-extension's release-selection logic + # always considers cppalliance/mrdocs' rolling `develop`/`master` release + # tags first regardless of any `version:` pin here, so the exact MrDocs + # build used isn't pinned and can vary run to run. Don't let the + # resulting dangling-xref noise hard-fail the build; a real extraction + # failure still raises above `fatal`. Safe to tighten back to `error` + # once #1277 is closed. failure_level: fatal diff --git a/doc/mrdocs.yml b/doc/mrdocs.yml index fe4f419785..327e6a414c 100644 --- a/doc/mrdocs.yml +++ b/doc/mrdocs.yml @@ -6,7 +6,7 @@ # # Official repository: https://github.com/boostorg/gil # -# Wired into antora.yml as ext: cpp-reference: config: doc/mrdocs.yml. +# Wired into antora.yml as ext: cppReference: config: doc/mrdocs.yml. # # GIL's extension/io/{jpeg,png,tiff,bmp,pnm,raw} backends need the matching # external image libraries just to parse, so mrdocs-src/all.cpp deliberately @@ -17,9 +17,9 @@ # # `compilation-database` is generated by build_antora.sh (gitignored) since # it needs the resolved $BOOST_SRC_DIR baked into its include path. The file -# must be literally named `compile_commands.json` -- MrDocs 0.8.0+47bdd690824e -# silently rejects any other basename with "Invalid compilation database -# path", even given as an absolute path to a file that exists and parses. +# must be literally named `compile_commands.json` -- MrDocs silently rejects +# any other basename with "Invalid compilation database path", even given +# as an absolute path to a file that exists and parses. source-root: .. input: diff --git a/pixi.lock b/pixi.lock index ba1c3e5aea..6a6a9f3e86 100644 --- a/pixi.lock +++ b/pixi.lock @@ -9,12 +9,10 @@ platforms: environments: default: channels: - - url: https://conda.anaconda.org/sdebionne/label/esrf-bcu/ - url: https://conda.anaconda.org/conda-forge/ packages: {} docs: channels: - - url: https://conda.anaconda.org/sdebionne/label/esrf-bcu/ - url: https://conda.anaconda.org/conda-forge/ packages: linux-64: @@ -44,7 +42,6 @@ environments: - conda: https://conda.anaconda.org/conda-forge/noarch/libstdcxx-devel_linux-64-15.3.0-hb2c5482_104.conda - conda: https://conda.anaconda.org/conda-forge/noarch/sysroot_linux-64-2.28-h4ee821c_9.conda - conda: https://conda.anaconda.org/conda-forge/noarch/tzdata-2026c-h151e31d_0.conda - - conda: https://conda.anaconda.org/sdebionne/label/esrf-bcu/linux-64/mrdocs-0.8.0-hb0f4dca_0.conda packages: - conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-20_gnu.conda build_number: 20 @@ -373,9 +370,3 @@ packages: run_exports: {} size: 118849 timestamp: 1784250406640 -- conda: https://conda.anaconda.org/sdebionne/label/esrf-bcu/linux-64/mrdocs-0.8.0-hb0f4dca_0.conda - sha256: e94797f3625b895e0ae0fc8c9edb6d750531416fb216608d60ad990efcf24210 - md5: ba3589b52b90663769840e331ee33b3e - license: Apache-2.0 WITH LLVM-exception - size: 54790420 - timestamp: 1788428774442 diff --git a/pixi.toml b/pixi.toml index 869546f41d..2ccd6cdacc 100644 --- a/pixi.toml +++ b/pixi.toml @@ -6,14 +6,14 @@ # # Official repository: https://github.com/boostorg/gil # -# Tooling for building the documentation (doc/). See doc/build_antora.sh. -# `mrdocs` comes from a personal channel repackaging a fixed MrDocs dev -# build (0.8.0+47bdd690824e) -- see doc/mrdocs.yml and the upstream issue -# at https://github.com/cppalliance/mrdocs/issues for the segfault it fixes. -# Drop this dependency once that fix is in an official MrDocs release. +# Tooling for building the documentation (doc/) locally. See +# doc/build_antora.sh -- MrDocs itself is fetched automatically by +# @cppalliance/antora-cpp-reference-extension (the latest release, as of +# MrDocs 2026.9.4 that's a fixed build for GIL's headers), so it isn't a +# pixi dependency. [workspace] -channels = ["sdebionne/label/esrf-bcu", "conda-forge"] +channels = ["conda-forge"] name = "gil" platforms = ["linux-64"] version = "0.1.0" @@ -21,7 +21,6 @@ version = "0.1.0" [feature.docs.dependencies] nodejs = "20.*" cxx-compiler = "*" -mrdocs = "*" [feature.docs.tasks] docs-build = "cd doc && bash build_antora.sh" From 1b86699ced4244323f3251622ca285a23ff8bf58 Mon Sep 17 00:00:00 2001 From: Samuel Debionne Date: Mon, 7 Sep 2026 13:21:21 +0200 Subject: [PATCH 2/2] docs: fix README's stale Doxygen references Leftover from the interim-Doxygen phase of the MrDocs migration and never updated when MrDocs replaced it -- doxyfile doesn't even exist anymore. Co-Authored-By: Claude Sonnet 5 --- .gitignore | 3 ++- doc/README.md | 15 ++++++++------- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index bbc4675887..6e91d0a50b 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,8 @@ stdcerr /doc/build/ /io/output -# Documentation (Antora + Doxygen) +# Documentation (Antora + MrDocs) +.tools doc/html doc/warnings.txt doc/node_modules diff --git a/doc/README.md b/doc/README.md index dc5614c2b5..f078ff425b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,17 +3,18 @@ A simple guide about writing and building documentation for Boost.GIL. The documentation is written in AsciiDoc and built with [Antora](https://antora.org/). -The C++ API reference is still generated with [Doxygen](https://www.doxygen.org) -(see `doxyfile`) and stitched into the Antora site by -`modules/ROOT/pages/reference.adoc` — this library is expected to move to a -[MrDocs](https://github.com/cppalliance/mrdocs)-generated, AsciiDoc-native -reference once an upstream MrDocs crash on GIL's header patterns is fixed; -see `mrdocs.yml` for details. +The C++ API reference is generated from the header comments with +[MrDocs](https://github.com/cppalliance/mrdocs) (see `mrdocs.yml` and +`mrdocs-src/all.cpp`) and wired into the Antora site as the `reference:` +module, with `modules/ROOT/pages/reference.adoc` as a curated landing page +into it. MrDocs itself isn't a build dependency here -- it's downloaded +automatically by the `@cppalliance/antora-cpp-reference-extension` Antora +extension the first time the reference is built. ## Prerequisites - [Node.js](https://nodejs.org/) 20+ (for Antora) -- [Doxygen](https://www.doxygen.org) +- A C++ compiler (for MrDocs to parse GIL's headers) Both are available through the repository's `pixi.toml` under the `docs` environment; from the repository root: