docs: migrate from Sphinx/RST/Doxygen to Antora/AsciiDoc - #797
Merged
Merged
Conversation
Contributor
Author
|
Well I don't deserve the credit on this one, my AI agent did most of the work... The result is very promising, hoping that the MrDocs bugs are not too difficult to fix. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #797 +/- ##
===========================================
+ Coverage 82.05% 82.85% +0.79%
===========================================
Files 117 119 +2
Lines 5383 5634 +251
===========================================
+ Hits 4417 4668 +251
Misses 966 966 🚀 New features to boost your workflow:
|
Contributor
Author
|
@mloskot Here is the documentation built locally (I am working on the CI now): site.tar.gz. IMHO, It's great improvement. |
Convert all prose documentation under doc/ to AsciiDoc pages built with Antora, following the boostorg/redis and boostorg/url convention (antora.yml, nav.adoc, build_antora.sh, package.json). Fix two pre-existing navigation gaps in the process: the contrast_enhancement pages that were unreachable from the old toctree, and the duplicated histogram/extension inclusion. The C++ API reference stays Doxygen-generated for now and is linked in via modules/ROOT/pages/reference.adoc: MrDocs 0.8.0 segfaults on most of GIL's CRTP-based pixel/image/iterator/locator headers, so a MrDocs-native reference (mrdocs.yml is prepared but not wired into antora.yml) is blocked on an upstream fix. Update the docs CI actions and pixi.toml's new `docs` environment (Node.js + Doxygen) accordingly, and remove the old Sphinx toolchain files. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace the interim Doxygen reference (see previous commit) with a real
MrDocs-generated one, now that the upstream segfault blocking it is fixed
(verified against a fixed MrDocs dev build against all 49 previously-crashing
GIL headers, and against the full public API: 6796 declarations, 5662 pages).
- doc/mrdocs-src/all.cpp: the single translation unit MrDocs extracts from --
core + concepts + image_processing + the dynamic_image/toolbox/numeric/
histogram extensions + the generic io layer. Deliberately excludes
extension/io/{jpeg,png,tiff,bmp,pnm,raw}, which need the matching external
image libraries just to parse.
- doc/mrdocs.yml: scoped to that same surface; compilation-database is
generated by build_antora.sh since it needs $BOOST_SRC_DIR baked in.
- antora.yml: ext.cppReference wired in (camelCase -- the extension doesn't
read the kebab-case key the public docs guide shows).
- reference.adoc: rewritten from the Doxygen stopgap to a curated table of
xref:reference:boost/gil/<Symbol>.adoc[] links, grouped by the categories
the old doc/reference.dox Doxygen-group taxonomy used (that taxonomy has
no equivalent in MrDocs' output, which groups by namespace/file instead).
- design/*.adoc: the ~45 concept deep-links that used to point at Doxygen
HTML now point at the real MrDocs reference pages instead.
- doxyfile, reference.dox, header.html, footer.html, doxygen-boost.css:
removed, no longer needed.
- local-playbook.yml: failure_level set to `fatal` rather than `error` --
some MrDocs-generated pages (e.g. packed_pixel) link to private-member
sub-pages (`_bitfield`) that MrDocs doesn't actually emit regardless of
extract-private; cosmetic, worth another small upstream report, but not
worth hard-failing the build over.
- .gitignore: `/doc/*build*` was accidentally also matching and silently
untracking doc/build_antora.sh this whole time (the same trap the
pre-existing `!build.jam` exception below it was clearly added for
before); narrowed to `/doc/build/`, and doc/build_antora.sh is now
actually tracked.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
setup-boost's `cp -r $GITHUB_WORKSPACE/* libs/gil` (into ../boost-root) drops .git (cp -r with a glob doesn't match dotfiles), but local-playbook.yml's Antora content source (`url: ..`) requires a real git repository. Found via the docs-ci-smoke test branch: FATAL (antora): Local content source must be a git repository: /home/runner/work/gil/boost-root/libs/gil (url: ..) Run the build from the original checkout instead (which does have .git), and only use ../boost-root for BOOST_SRC_DIR (MrDocs' cross-library header resolution), matching how boostorg/url and boostorg/redis's CI scripts keep those two concerns separate. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Add libs/gil/pixi.toml -- a self-contained `docs` environment (Node, a C++ compiler, and MrDocs from the sdebionne/label/esrf-bcu channel, which repackages a fixed MrDocs dev build until the upstream segfault fix ships in an official release) -- so `pixi run -e docs docs-build` is a fully self-contained one-command local build. build_antora.sh now auto-detects a pixi/conda-provided MrDocs via CONDA_PREFIX when MRDOCS_ROOT isn't already set, instead of falling through to the antora-cpp-reference-extension's auto-download (which currently fetches the still-broken official release). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
docs-prerequisites now sets up the pixi `docs` environment instead of a plain Node install, and generate-doc runs the build through `pixi run -e docs docs-build`. Without this, a real push to develop/master would still hit the antora-cpp-reference-extension's auto-download of the official MrDocs release, which segfaults on GIL's headers -- validated end-to-end on the docs-ci-smoke test branch first. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
sdebionne
force-pushed
the
doc-migrate-to-asciidoc
branch
from
September 3, 2026 11:09
7b9e276 to
c889bcb
Compare
sdebionne
marked this pull request as ready for review
September 3, 2026 11:10
Contributor
Author
|
@mloskot It might be easier for you to review the doc with https://boostorg.github.io/gil/develop/doc/gil/index.html now that the CI works. |
Member
|
@sdebionne This looks fantastic |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Convert all prose documentation under doc/ to AsciiDoc pages built with Antora, following the boostorg/redis and boostorg/url convention (antora.yml, nav.adoc, build_antora.sh, package.json). Fix two pre-existing navigation gaps in the process: the contrast_enhancement pages that were unreachable from the old toctree, and the duplicated histogram/extension inclusion.
The C++ API reference stays Doxygen-generated for now and is linked in via modules/ROOT/pages/reference.adoc: MrDocs 0.8.0 segfaults on most of GIL's CRTP-based pixel/image/iterator/locator headers, so a MrDocs-native reference (mrdocs.yml is prepared but not wired into antora.yml) is blocked on an upstream fix.
Update the docs CI actions and remove the old Sphinx toolchain files.
References
Closes #782
Closes #783
Tasklist