build_antora.sh: patch base-url with permalink

jll63 · jll63 · commit 52fa71306e1c · 2025-11-15T15:44:36.000-05:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -123,5 +123,5 @@ jobs:
           path: doc/html
 
       - name: Deploy to GitHub Pages (jll63)
-        if: matrix.os == 'ubuntu-latest' && github.repository_owner == 'jll63' && github.ref_name == 'feature/doc'
+        if: matrix.os == 'ubuntu-latest' && github.repository_owner == 'jll63'
         uses: actions/deploy-pages@v4
diff --git a/doc/build_antora.sh b/doc/build_antora.sh
@@ -11,6 +11,7 @@
 
 set -e
 
+
 if [ $# -eq 0 ]
   then
     echo "No playbook supplied, using default playbook"
@@ -22,6 +23,24 @@ fi
 SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 cd "$SCRIPT_DIR"
 
+if [ -n "${CIRCLE_REPOSITORY_URL:-}" ]; then
+  account="${CIRCLE_REPOSITORY_URL#*:}"
+  account="${account%%/*}"
+  lib=$(basename "$(git rev-parse --show-toplevel)")
+  repository="${account}/$lib"
+  sha=${CIRCLE_SHA1}
+elif [ -n "${GITHUB_REPOSITORY:-}" ]; then
+  repository="${GITHUB_REPOSITORY}"
+  sha=${GITHUB_SHA}
+fi
+
+if [ -n "${repository}" ] && [ -n "${sha}" ]; then
+  base_url="https://github.com/${repository}/blob/${sha}"
+  echo "Setting base-url to $base_url"
+  cp mrdocs.yml mrdocs.yml.bak
+  perl -i -pe 's{^\s*base-url:.*$}{base-url: '"$base_url/"'}' mrdocs.yml
+fi
+
 echo "Building documentation with Antora..."
 echo "Installing npm dependencies..."
 npm ci
@@ -37,4 +56,15 @@ for f in $(find html -name '*.html'); do
   perl -i -pe 's{&lcub;&lcub;(.*?)&rcub;&rcub;}{<a href="../../../$1.html">$1</a>}g' "$f"
 done
 
+if [ -n "${base_url:-}" ]; then
+  if [ -f mrdocs.yml.bak ]; then
+    mv -f mrdocs.yml.bak mrdocs.yml
+    echo "Restored original mrdocs.yml"
+  else
+    echo "mrdocs.yml.bak not found; skipping restore"
+  fi
+  perl -i -pe "s[{{BASE_URL}}][$base_url]g" \
+    html/openmethod/ref_headers.html html/openmethod/BOOST_OPENMETHOD*.html
+fi
+
 echo "Done"
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD.adoc
@@ -3,7 +3,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 BOOST_OPENMETHOD(ID, (PARAMETERS...), RETURN_TYPE [, REGISTRY]);
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_CLASSES.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_CLASSES.adoc
@@ -5,7 +5,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 BOOST_OPENMETHOD_CLASSES(CLASSES...[, REGISTRY]);
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_DECLARE_OVERRIDER.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_DECLARE_OVERRIDER.adoc
@@ -3,7 +3,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 #define BOOST_OPENMETHOD_DECLARE_OVERRIDER(NAME, (PARAMETERS...), RETURN_TYPE)
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_DEFINE_OVERRIDER.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_DEFINE_OVERRIDER.adoc
@@ -3,7 +3,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 #define BOOST_OPENMETHOD_DEFINE_OVERRIDER(ID, (PARAMETERS...), RETURN_TYPE)
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_ID.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_ID.adoc
@@ -5,7 +5,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 #define BOOST_OPENMETHOD_ID(ID) /* unspecified */
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_INLINE_OVERRIDE.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_INLINE_OVERRIDE.adoc
@@ -5,7 +5,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 BOOST_OPENMETHOD_INLINE_OVERRIDE(ID, (PARAMETERS...), RETURN_TYPE) {
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDE.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDE.adoc
@@ -5,7 +5,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 BOOST_OPENMETHOD_OVERRIDE(ID, (PARAMETERS...), RETURN_TYPE) {
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDER.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDER.adoc
@@ -3,7 +3,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 #define BOOST_OPENMETHOD_OVERRIDER(ID, (PARAMETERS...), RETURN_TYPE)
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDERS.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_OVERRIDERS.adoc
@@ -3,7 +3,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 #define BOOST_OPENMETHOD_OVERRIDERS(ID)                                      \
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_REGISTER.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_REGISTER.adoc
@@ -5,7 +5,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 BOOST_OPENMETHOD_REGISTER(TYPE);
diff --git a/doc/modules/ROOT/pages/BOOST_OPENMETHOD_TYPE.adoc b/doc/modules/ROOT/pages/BOOST_OPENMETHOD_TYPE.adoc
@@ -3,7 +3,7 @@
 
 ### Synopsis
 
-Defined in <boost/openmethod/macros.hpp>.
+Defined in link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>].
 
 ```c++
 BOOST_OPENMETHOD_TYPE(ID, (PARAMETERS...), RETURN_TYPE [, REGISTRY]);
diff --git a/doc/modules/ROOT/pages/ref_headers.adoc b/doc/modules/ROOT/pages/ref_headers.adoc
@@ -7,21 +7,64 @@
 
 The following headers are sufficient for most basic uses of the library.
 
-* xref:#main[`boost/openmethod.hpp`] to define open-methods and overriders using
+* xref:#openmethod[`<boost/openmethod.hpp>`] to define open-methods and overriders using
 convenient macros.
 
-* xref:#initialize[`boost/openmethod/initialize.hpp`] to initialize the library.
+* xref:#initialize[`<boost/openmethod/initialize.hpp>`] to initialize the library.
 Typically only included in the translation unit containing `main`.
 
 The following headers make it possible to use standard smart pointers in virtual
 parameters:
 
-* xref:#std_shared_ptr[`boost/openmethod/interop/std_shared_ptr.hpp`] to use
+* xref:#std_shared_ptr[`<boost/openmethod/interop/std_shared_ptr.hpp>`] to use
 `std::shared_ptr` in virtual parameters.
 
-* xref:#std_unique_ptr[`boost/openmethod/interop/std_unique_ptr.hpp`] to use
+* xref:#std_unique_ptr[`<boost/openmethod/interop/std_unique_ptr.hpp>`] to use
 `std::unique_ptr` in virtual parameters.
 
+## High-level Headers
+
+[#core]
+### link:{{BASE_URL}}/include/boost/openmethod/core.hpp[<boost/openmethod/core.hpp>]
+
+Defines the main constructs of the library: methods, overriders and virtual
+pointers, and mechanisms to implement them. Does not define any public macros
+apart from `BOOST_OPENMETHOD_DEFAULT_REGISTRY`, if it is not defined already.
+
+[#macros]
+### link:{{BASE_URL}}/include/boost/openmethod/macros.hpp[<boost/openmethod/macros.hpp>]
+
+Defines the public macros of the library, such as `BOOST_OPENMETHOD`,
+`BOOST_OPENMETHOD_CLASSES`, etc.
+
+There is little point in including this header directly, as this has the same
+effect as including `boost/openmethod.hpp`, which is shorter.
+
+[#openmethod]
+### link:{{BASE_URL}}/include/boost/openmethod.hpp[<boost/openmethod.hpp>]
+
+Includes `core.hpp` and `macros.hpp`.
+
+[#initialize]
+### link:{{BASE_URL}}/include/boost/initialize.hpp[<boost/initialize.hpp>]
+
+Provides the cpp:initialize[] and cpp:finalize[] functions. This header is
+typically included in the translation unit containing `main`. Translation units
+that dynamically load or unload shared libraries may also need to call those
+functions.
+
+[#std_shared_ptr]
+### link:{{BASE_URL}}/include/boost/openmethod/interop/std_shared_ptr.hpp[<boost/openmethod/interop/std_shared_ptr.hpp>]
+
+Provides a `virtual_traits` specialization that makes it possible to use a
+`std::shared_ptr` in place of a raw pointer or reference in virtual parameters.
+
+[#std_unique_ptr]
+### link:{{BASE_URL}}/include/boost/openmethod/interop/std_unique_ptr.hpp[<boost/openmethod/interop/std_unique_ptr.hpp>]
+
+Provides a `virtual_traits` specialization that makes it possible to use a
+`std::unique_ptr` in place of a raw pointer or reference in virtual parameters.
+
 *The headers below are for advanced use*.
 
 ## Pre-Core Headers
@@ -30,82 +73,52 @@ The following headers can be included before `core.hpp` to define custom
 registries and policies, and override the default registry by defining
 xref:BOOST_OPENMETHOD_DEFAULT_REGISTRY.adoc[`BOOST_OPENMETHOD_DEFAULT_REGISTRY`].
 
-### boost/openmethod/preamble.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/preamble.hpp[<boost/openmethod/preamble.hpp>]
 
 Defines `registry` and stock policy categories. Also defines all types and
 functions necessary for the definition of `registry`.
 
-### boost/openmethod/policies/std_rtti.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/std_rtti.hpp[<boost/openmethod/policies/std_rtti.hpp>]
 
 Provides an implementation of the `rtti` policy using standard RTTI.
 
-### boost/openmethod/policies/fast_perfect_hash.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/fast_perfect_hash.hpp[<boost/openmethod/policies/fast_perfect_hash.hpp>]
 
 Provides an implementation of the `hash` policy using a fast perfect hash
 function.
 
-### boost/openmethod/policies/vptr_vector.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/vptr_vector.hpp[<boost/openmethod/policies/vptr_vector.hpp>]
 
 Provides an implementation of the `vptr` policy that stores the v-table pointers
 in a `std::vector` indexed by type ids, possibly hashed.
 
-### boost/openmethod/policies/default_error_handler.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/default_error_handler.hpp[<boost/openmethod/policies/default_error_handler.hpp>]
 
 Provides an implementation of the `error_handler` policy that calls a
 `std::function<void(openmethod_error)>` when an error is encountered, and before
 the library aborts the program.
 
-### boost/openmethod/policies/stderr_output.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/stderr_output.hpp[<boost/openmethod/policies/stderr_output.hpp>]
 
 Provides an implementation of the `output` policy that writes diagnostics to
 the C standard error stream (not using iostreams).
 
-### boost/openmethod/default_registry.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/default_registry.hpp[<boost/openmethod/default_registry.hpp>]
 
 Defines the default registry, which contains all the stock policies listed
-above. Includes all the headers listed in the preamble section so far.
+above. Includes all the headers listed in this section so far.
 
-### boost/openmethod/policies/static_rtti.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/static_rtti.hpp[<boost/openmethod/policies/static_rtti.hpp>]
 
 Provides a minimal implementation of the `rtti` policy that does not depend on
 standard RTTI.
 
-### boost/openmethod/policies/throw_error_handler.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/throw_error_handler.hpp[<boost/openmethod/policies/throw_error_handler.hpp>]
 
 Provides an implementation of the `error_handler` policy that throws errors as
 exceptions.
 
-### boost/openmethod/policies/vptr_map.hpp
+### link:{{BASE_URL}}/include/boost/openmethod/policies/vptr_map.hpp[<boost/openmethod/policies/vptr_map.hpp>]
 
 Provides an implementation of the `vptr` policy that stores the v-table pointers
 in a map (by default a `std::map`) indexed by type ids.
-
-## High-level Headers
-
-### boost/openmethod/core.hpp
-
-Defines the main constructs of the library: methods, overriders and virtual
-pointers, and mechanisms to implement them. Does not define any public macros
-apart from `BOOST_OPENMETHOD_DEFAULT_REGISTRY`, if it is not defined already.
-
-### boost/openmethod/macros.hpp
-
-Defines the public macros of the library, such as `BOOST_OPENMETHOD`,
-`BOOST_OPENMETHOD_CLASSES`, etc.
-
-There is little point in including this header directly, as this has the same
-effect as including `boost/openmethod.hpp`, which is shorter.
-
-### boost/openmethod.hpp
-
-Includes `core.hpp` and `macros.hpp`.
-
-### boost/openmethod/interop/std_shared_ptr.hpp
-
-Provides a `virtual_traits` specialization that make it possible to use a
-`std::shared_ptr` in place of a raw pointer or reference in virtual parameters.
-
-### boost/openmethod/interop/std_unique_ptr.hpp
-
-Provides a `virtual_traits` specialization that make it possible to use a
-`std::unique_ptr` in place of a raw pointer or reference in virtual parameters.
