diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7483e137..77302bc1 100644 --- 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 index 7788527a..de78f144 100755 --- 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{{{(.*?)}}}{$1}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 index 420a13bc..2fac8a84 100644 --- a/doc/modules/ROOT/pages/BOOST_OPENMETHOD.adoc +++ b/doc/modules/ROOT/pages/BOOST_OPENMETHOD.adoc @@ -3,7 +3,7 @@ ### Synopsis -Defined in . +Defined in link:{{BASE_URL}}/include/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 index be5045b9..26d32027 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 10dd37d3..a888a30f 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 24aa314d..54daf06e 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 319be17d..6fe5d508 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 006d6ea3..127da1da 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index a03cc99c..f29226e4 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 867483bb..9aa4e4bc 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 496d2bda..38160664 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index f57117ce..ac84168f 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 911e9182..94d8eb8d 100644 --- 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 . +Defined in link:{{BASE_URL}}/include/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 index 680a4aa9..82897caa 100644 --- 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[``] to define open-methods and overriders using convenient macros. -* xref:#initialize[`boost/openmethod/initialize.hpp`] to initialize the library. +* xref:#initialize[``] 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[``] 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[``] to use `std::unique_ptr` in virtual parameters. +## High-level Headers + +[#core] +### link:{{BASE_URL}}/include/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[] + +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[] + +Includes `core.hpp` and `macros.hpp`. + +[#initialize] +### link:{{BASE_URL}}/include/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[] + +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[] + +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[] 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[] 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[] 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[] 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[] Provides an implementation of the `error_handler` policy that calls a `std::function` 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[] 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[] 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[] 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[] 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[] 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. diff --git a/test/test_virtual_ptr_doc.cpp b/test/test_virtual_ptr_doc.cpp index d1ce509d..18b711b7 100644 --- a/test/test_virtual_ptr_doc.cpp +++ b/test/test_virtual_ptr_doc.cpp @@ -186,11 +186,14 @@ namespace non_polymorphic { struct Animal {}; // polymorphic not required struct Dog : Animal {}; // polymorphic not required BOOST_OPENMETHOD_CLASSES(Animal, Dog); + +// codecov:ignore:start BOOST_OPENMETHOD(poke, (virtual_ptr), void); -void instiantiate_poke(virtual_ptr snoopy) { +void instantiate_poke(virtual_ptr snoopy) { poke(snoopy); } +// codecov:ignore:end BOOST_AUTO_TEST_CASE(virtual_ptr_examples_non_polymorphic) { {