Prepare for v1.93

.github/actions/docs-prerequisites/action.yml

@@ -3,5 +3,6 @@ description: 'Downloads all the necessary packages for building documentation'
 runs:
   using: composite
   steps:
-    - run: sudo apt-get install doxygen python3 python3-pip python3-setuptools  python3-sphinx 
-      shell: bash
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20

.github/actions/generate-doc/action.yml

@@ -1,13 +1,16 @@
 name: 'Generate Doc'
-description: 'Runs b2 on lib/gil/doc to generate documentation'
+description: 'Builds the Antora documentation for lib/gil/doc'
 runs:
   using: composite
   steps:
     - run: |
-        echo "using doxygen ;" > ~/user-config.jam
-        cd ../boost-root/libs
-        ../b2 gil/doc
-        cd gil
+        # setup-boost copies the checkout (with .git, via `cp -a`) into
+        # ../boost-root/libs/gil, so doc/ is nested under a real Boost
+        # superproject there -- needed by build_antora.sh's BOOST_SRC_DIR
+        # detection and by Antora's local content source.
+        cd ../boost-root/libs/gil/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

.github/actions/generate-doc/docs-config.sh

@@ -15,18 +15,16 @@ git switch gh-pages
 
 if [ "${GITHUB_REF##*/}" = develop ]; then
     # Only updates develop directory and keeps others intact
-    rm -r develop
+    rm -rf develop
     mkdir -p develop/doc
     cp ../index.html develop/
-    cp ../doc/index.html develop/doc
-    cp -a ../doc/html develop/doc/
+    cp -a ../doc/html/. develop/doc/
 else
     # main branch
-    rm index.html
-    rm -r html
-    cp ../doc/index.html .
-    cp -r ../doc/html .
+    rm -f index.html
+    rm -rf html gil
+    cp -a ../doc/html/. .
 fi
 
 # Remove version control
-rm -rf .git
+rm -rf .git

.github/actions/setup-boost/action.yml

@@ -9,7 +9,7 @@ runs:
         cd ..
         git clone -b $BOOST_BRANCH --depth 1 https://github.com/boostorg/boost.git boost-root
         cd boost-root
-        cp -r $GITHUB_WORKSPACE/* libs/gil
+        cp -a $GITHUB_WORKSPACE/. libs/gil/
         git submodule update --init tools/boostdep
         python tools/boostdep/depinst/depinst.py --git_args "--jobs 3" gil
         ./bootstrap.sh

.gitignore

@@ -4,12 +4,14 @@
 
 # Boost.Build
 stdcerr
-/doc/*build*
+/doc/build/
 /io/output
 
-# Documentation and Sphinx
+# Documentation (Antora + MrDocs)
+.tools
 doc/html
 doc/warnings.txt
+doc/node_modules
 
 # Visual Studio (Code)
 /.vs

CMakeLists.txt

@@ -32,6 +32,7 @@ target_link_libraries(boost_gil
     Boost::iterator
     Boost::mp11
     Boost::preprocessor
+    Boost::stl_interfaces
     Boost::type_traits
     Boost::variant2
 )

doc/CMakeLists.txt

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2026 Samuel Debionne 
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+
+# Root CMakeLists.txt so MrDocs knows how to build our code
+cmake_minimum_required(VERSION 3.8...3.22)
+
+# Project
+project(boost_gil_mrdocs LANGUAGES CXX)
+
+# MrDocs forces CMAKE_EXPORT_COMPILE_COMMANDS=ON, incorrectly
+# causing all targets to be dumped to the compilation database.
+# Disable this setting so we can set EXPORT_COMPILE_COMMANDS
+# only to our target of interest
+set(CMAKE_EXPORT_COMPILE_COMMANDS OFF)
+
+# Add Boost
+add_subdirectory($ENV{BOOST_SRC_DIR} deps/boost)
+
+# Add the target for mrdocs to analyze
+add_executable(mrdocs mrdocs.cpp)
+target_link_libraries(mrdocs PRIVATE Boost::gil)
+set_target_properties(mrdocs PROPERTIES EXPORT_COMPILE_COMMANDS ON)

doc/Jamfile

@@ -1,66 +1,25 @@
-# Boost.GIL (Generic Image Library) - documentation
 #
 # Copyright (c) 2018 Stefan Seefeld
+# Copyright (c) 2026 Samuel Debionne
 #
 # Distributed under the Boost Software License, Version 1.0. (See accompanying
 # file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
 
-import doxygen ;
-import os ;
-import path ;
-
-.doxygen = [ doxygen.name ] ;
-.doxygen ?= doxygen ;
-
-#doxygen/gil_standalone/gil_boost.doxygen
-make reference : doxyfile
-     : @make_doxygen
-     : <location>html
-       <dependency>$(headers)
-     ;
+# Adapted from Boost.Redis
+make html/index.html : build_antora.sh : @run-script ;
 
-rule make_doxygen ( targets * : sources * : properties * )
-{
-    LIB_DIR on $(targets) =
-        [ path.native [ path.parent [ path.root
-        [ on $(sources[1]) return $(SEARCH) ] [ path.pwd ] ] ] ] ;
-}
-
-if [ os.name ] = NT
-{
-    actions make_doxygen
-    {
-        SET LIB_DIR=$(LIB_DIR)
-        chdir "$(>:D)" && "$(.doxygen)" $(>:D=)
-    }
-}
-else
+# Runs the Antora script
+actions run-script
 {
-    actions make_doxygen
-    {
-        export LIB_DIR=$(LIB_DIR)
-        cd $(>:D) && "$(.doxygen)" $(>:D=)
-    }
+    bash -x $(>)
 }
 
-make html
-     : index.rst
-     : @sphinx-build
-     : <location>.
-       <dependency>reference
-     ;
+# These are used to inform the build system of the
+# means to build the integrated and stand-alone docs.
 
-if [ os.name ] = NT
-{
-  actions sphinx-build { chdir "$(>:D)" && make clean && make html}
-}
-else
-{
-  actions sphinx-build { make -C "$(>:D)" clean html}
-}
-
-###############################################################################
 alias boostdoc ;
 explicit boostdoc ;
-alias boostrelease : html ;
+
+alias boostrelease : html/index.html ;
 explicit boostrelease ;

doc/README.md

@@ -2,33 +2,32 @@
 
 A simple guide about writing and building documentation for Boost.GIL.
 
-## Prerequisites
-
-- Python 3
-- Install [Sphinx](https://www.sphinx-doc.org/en/master/index.html) (see `requirements.txt`)
-- Install [Doxygen](http://www.doxygen.org)
+The documentation is written in AsciiDoc and built with [Antora](https://antora.org/).
+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
 
-## Installation
+- [Node.js](https://nodejs.org/) 20+ (for Antora)
+- A C++ compiler (for MrDocs to parse GIL's headers)
 
-Create Python virtual environment:
+Both are available through the repository's `pixi.toml` under the `docs`
+environment; from the repository root:
 
 ```console
-$ python3 -m venv .venv
-$ source ~/.venv/bin/activate
+$ pixi run -e docs docs-build
 ```
 
-Install Sphinx and Sphinx extensions:
+## Build manually
 
 ```console
-(.venv)$ cd boost-root
-(.venv)$ pip install -r libs/gil/doc/requirements.txt
+$ cd libs/gil/doc
+$ bash build_antora.sh
 ```
 
-## Build
-
-```console
-$ echo "using doxygen ;" > ~/user-config.jam
-$ cd boost-root
-$ b2 libs/gil/doc
-```
+The site is generated at `doc/html/index.html`.