Port the documentation to MrDocs and Antora

CMakeLists.txt

@@ -1,5 +1,6 @@
 # Generated by `boostdep --cmake dynamic_bitset`
 # Copyright 2020 Peter Dimov
+# Copyright 2025 Gennaro Prota
 # Distributed under the Boost Software License, Version 1.0.
 # https://www.boost.org/LICENSE_1_0.txt
 
@@ -30,3 +31,21 @@ if(BUILD_TESTING AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt")
 
 endif()
 
+if (DYNAMIC_BITSET_MRDOCS_BUILD)
+    set(INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include")
+
+    # Create a temporary source file that includes boost/dynamic_bitset.hpp.
+    set(TEMP_CPP_FILE "${CMAKE_CURRENT_BINARY_DIR}/dynamic_bitset_for_mrdocs.cpp")
+    file(WRITE ${TEMP_CPP_FILE} "// This file is generated automatically by CMake\n\n")
+    file(APPEND ${TEMP_CPP_FILE} "#include \"boost/dynamic_bitset.hpp\"\n")
+
+    # Create a custom target for MrDocs.
+    add_library(dynamic_bitset_mrdocs_target ${TEMP_CPP_FILE})
+
+    # Set any other target properties here.
+    target_include_directories(dynamic_bitset_mrdocs_target PRIVATE ${INCLUDE_DIR})
+    target_link_libraries(dynamic_bitset_mrdocs_target PRIVATE boost_dynamic_bitset)
+
+    # Don't create any other targets.
+    return()
+endif()

doc/antora.yml

@@ -0,0 +1,21 @@
+# ============================================================================
+#                        Copyright 2025 Gennaro Prota.
+#
+#          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)
+# ============================================================================
+
+name: dynamic_bitset
+version: ~
+title: Boost.DynamicBitset
+start_page: index.adoc
+asciidoc:
+  attributes:
+    source-language: asciidoc@
+    table-caption: false
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  cpp-reference:
+    config: doc/mrdocs.yml

doc/build_docs.sh

@@ -0,0 +1,28 @@
+#! /bin/sh --
+# ============================================================================
+#                       Copyright 2023 Alan de Freitas.
+#                        Copyright 2025 Gennaro Prota.
+#
+#          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)
+# ============================================================================
+
+set -eu
+
+if [ $# -eq 0 ]
+then
+    echo "No playbook supplied, using default playbook."
+    PLAYBOOK="local-playbook.yml"
+else
+    PLAYBOOK=$1
+fi
+
+echo "Installing npm dependencies..."
+npm ci
+
+echo "Building docs in custom dir..."
+PATH="$(pwd)/node_modules/.bin:${PATH}"
+export PATH
+npx antora --clean --fetch "$PLAYBOOK" --stacktrace --log-level all
+echo "Done"

doc/local-playbook.yml

@@ -0,0 +1,55 @@
+# ============================================================================
+#                       Copyright 2023 Alan de Freitas.
+#                        Copyright 2025 Gennaro Prota.
+#
+#          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)
+# ============================================================================
+#
+#       An antora playbook used for local development.
+#       The playbook includes Boost.DynamicBitset as its only component.
+# ----------------------------------------------------------------------------
+
+site:
+  title: Boost.DynamicBitset
+  url: https://antora.cppalliance.org/develop/lib/doc
+  start_page: dynamic_bitset::index.adoc
+  robots: allow
+  keys:
+    repo_url: 'https://github.com/boostorg/dynamic_bitset'
+
+content:
+  sources:
+    - url: ..
+      start_path: doc
+      edit_url: 'https://github.com/boostorg/dynamic_bitset/edit/{refname}/{path}'
+
+ui:
+  bundle:
+    url: https://github.com/boostorg/website-v2-docs/releases/download/ui-master/ui-bundle.zip
+    snapshot: true
+
+antora:
+  extensions:
+    - require: '@antora/lunr-extension' # https://gitlab.com/antora/antora-lunr-extension
+      index_latest_only: true
+    - require: '@cppalliance/antora-cpp-tagfiles-extension'
+      cpp-tagfiles:
+        using-namespaces:
+          - 'boost::'
+    - require: '@cppalliance/antora-cpp-reference-extension'
+      dependencies:
+        - name: 'boost'
+          repo: 'https://github.com/boostorg/boost.git'
+          tag: 'develop'
+          variable: 'BOOST_SRC_DIR'
+          system-env: 'BOOST_SRC_DIR'
+
+asciidoc:
+  attributes:
+    # Enable pagination
+    page-pagination: ''
+  extensions:
+    - '@cppalliance/asciidoctor-boost-links'
+    - '@asciidoctor/tabs'

doc/modules/ROOT/nav.adoc

@@ -0,0 +1,10 @@
+// ===========================================================================
+//                        Copyright 2025 Gennaro Prota.
+//
+//         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)
+// ===========================================================================
+
+* xref:index.adoc[]
+* xref:reference.adoc[Reference]

doc/modules/ROOT/pages/index.adoc

@@ -0,0 +1,79 @@
+// ===========================================================================
+//                         Copyright 2001 Jeremy Siek
+//                Copyright 2003-2004, 2008, 2025 Gennaro Prota
+//                        Copyright 2014 Ahmed Charles
+//                     Copyright 2014 Riccardo Marcangelo
+//                        Copyright 2018 Evgeny Shulgin
+//
+//         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)
+// ===========================================================================
+
+= Boost.DynamicBitset
+
+Boost.DynamicBitset is a portable library that provides a set of bits.
+
+The set (`boost::dynamic_bitset`) provides access to the value of individual
+bits via `operator[]` and provides all of the bitwise operators that one can
+apply to builtin integers, such as `operator&` and `operator<<`. The number of
+bits can change at runtime.
+
+`dynamic_bitset` is nearly identical to `std::bitset`. The difference is that
+the size of a `dynamic_bitset` (the number of bits) can change at runtime,
+whereas the size of a `std::bitset` is specified at compile-time through an
+integer template parameter.
+
+The main problem that `dynamic_bitset` is designed to solve is that of
+representing a subset of a finite set. Each bit represents whether an element of
+the finite set is in the subset or not. As such the bitwise operations of
+`dynamic_bitset`, such as `operator&` and `operator|`, correspond to set
+operations, such as intersection and union.
+
+== Definitions
+Each bit represents either the Boolean value `true` or `false` (1 or 0). To set
+a bit is to assign it 1. To clear or reset a bit is to assign it 0. To flip a
+bit is to change the value to 1 if it was 0 and to 0 if it was 1. Each bit has a
+non-negative position. A bitset `x` contains `x.size()` bits, with each bit
+assigned a unique position in the range `[0, x.size())`. The bit at position 0
+is called the least significant bit and the bit at position `size() - 1` is the
+most significant bit. When converting an instance of `dynamic_bitset` to or from
+an unsigned long `n`, the bit at position `i` of the bitset has the same value
+as `(n >> i) & 1`.
+
+== Rationale
+`dynamic_bitset` is not a <a
+href="https://en.cppreference.com/w/cpp/named_req/Container.html">Container</a>
+and does not provide iterators for the following reason:
+
+A container with a proxy reference type can not fulfill the container
+requirements as specified in the C++ standard (unless one resorts to strange
+iterator semantics). `std::vector<bool>` has a proxy reference type and does not
+fulfill the container requirements and as a result has caused many problems. One
+common problem is when people try to use iterators from `std::vector<bool>` with
+a standard algorithm such as `std::search()`. The `std::search()` requirements
+say that the iterator must be a LegacyForwardIterator, but
+`std::vector<bool>::iterator` does not meet this requirement because of the
+proxy reference. Depending on the implementation, they may or not be a compile
+error or even a run-time error due to this misuse. For further discussion of the
+problem see "Effective STL" by Scott Meyers. So `dynamic_bitset` tries to avoid
+these problems by not pretending to be a container.
+
+Some people prefer the name "toggle" to "flip". The name "flip" was chosen
+because that is the name used in `std::bitset`. In fact, most of the function
+names for `dynamic_bitset` were chosen for this reason.
+
+`dynamic_bitset` does not throw exceptions when a precondition is violated (as
+is done in `std::bitset`). Instead `BOOST_ASSERT()` is used. See the guidelines
+for Error and Exception Handling for the explanation. Note that, consistently
+with this, the documentation of the member functions doesn't use the term
+"precondition" for conditions that cause an exception to be emitted (the C++
+standard uses the term "requires" in such cases).
+
+== Acknowledgments
+
+We would like to thank the Boost community for putting in the time to review and
+accept this library. This library is much better than it ever would have been
+due to all the suggestions from Boost members. We especially thank Matt Marcus
+for taking on the task of review manager. Also, a special thanks goes to James
+Kanze for his invaluable help with the internationalization issues.

doc/mrdocs.yml

@@ -0,0 +1,25 @@
+# ============================================================================
+#                        Copyright 2025 Gennaro Prota.
+#
+#          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)
+# ============================================================================
+
+verbose: true
+source-root: ..
+cmake: '-DDYNAMIC_BITSET_MRDOCS_BUILD=ON'
+input:
+  - ../include
+exclude-symbols:
+  - 'boost::detail'
+  - 'boost::detail::**'
+  - 'boost::to_string_helper'
+  - 'std'
+  - 'std::**'
+  #     Why does MrDocs pick up ::size_t?
+  - 'size_t'
+file-patterns:
+  - '*.hpp'
+multipage: false
+generator: adoc

doc/readme

@@ -1 +1 @@
-The documentation for the dynamic_bitset library is the top-level index.html file.
+To build the documentation, run build_docs.sh.

include/boost/dynamic_bitset/impl/dynamic_bitset.tpp

@@ -176,16 +176,6 @@ dynamic_bitset< Block, Allocator >::dynamic_bitset(
     init_from_string( s, pos, n, num_bits );
 }
 
-template< typename Block, typename Allocator >
-template< typename CharT, typename Traits, typename Alloc >
-dynamic_bitset< Block, Allocator >::dynamic_bitset(
-    const std::basic_string< CharT, Traits, Alloc > &             s,
-    typename std::basic_string< CharT, Traits, Alloc >::size_type pos )
-    : m_bits( Allocator() ), m_num_bits( 0 )
-{
-    init_from_string( s, pos, ( std::basic_string< CharT, Traits, Alloc >::npos ), npos );
-}
-
 template< typename Block, typename Allocator >
 template< typename BlockInputIterator >
 dynamic_bitset< Block, Allocator >::dynamic_bitset(