Drop custom MrDocs from CI

.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

.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

.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

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:

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

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

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:

pixi.toml

@@ -6,22 +6,21 @@
 #
 # 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"
 
 [feature.docs.dependencies]
 nodejs = "20.*"
 cxx-compiler = "*"
-mrdocs = "*"
 
 [feature.docs.tasks]
 docs-build = "cd doc && bash build_antora.sh"