docs: mrdocs target includes all headers

CMakeLists.txt

@@ -34,6 +34,7 @@ set(__ignore__ ${CMAKE_C_COMPILER})
 option(BOOST_URL_BUILD_TESTS "Build boost::url tests even if BUILD_TESTING is OFF" OFF)
 option(BOOST_URL_BUILD_FUZZERS "Build boost::url fuzzers" OFF)
 option(BOOST_URL_BUILD_EXAMPLES "Build boost::url examples" ${BOOST_URL_IS_ROOT})
+option(BOOST_URL_MRDOCS_BUILD "Build the target for MrDocs: see mrdocs.yml" OFF)
 option(BOOST_URL_DISABLE_THREADS "Disable threads" OFF)
 option(BOOST_URL_WARNINGS_AS_ERRORS "Treat warnings as errors" OFF)
 set(BOOST_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../.." CACHE STRING "Boost source dir to use when running CMake from this directory")
@@ -63,11 +64,13 @@ foreach (BOOST_URL_DEPENDENCY ${BOOST_URL_DEPENDENCIES})
     endif ()
 endforeach ()
 # Conditional dependencies
-if (BUILD_TESTING OR BOOST_URL_BUILD_TESTS)
-    set(BOOST_URL_UNIT_TEST_LIBRARIES container filesystem unordered)
-endif()
-if (BOOST_URL_BUILD_EXAMPLES)
-    set(BOOST_URL_EXAMPLE_LIBRARIES json regex beast)
+if (NOT BOOST_URL_MRDOCS_BUILD)
+    if (BUILD_TESTING OR BOOST_URL_BUILD_TESTS)
+        set(BOOST_URL_UNIT_TEST_LIBRARIES container filesystem unordered)
+    endif()
+    if (BOOST_URL_BUILD_EXAMPLES)
+        set(BOOST_URL_EXAMPLE_LIBRARIES json regex beast)
+    endif()
 endif()
 # Complete dependency list
 set(BOOST_INCLUDE_LIBRARIES ${BOOST_URL_INCLUDE_LIBRARIES} ${BOOST_URL_UNIT_TEST_LIBRARIES} ${BOOST_URL_EXAMPLE_LIBRARIES})
@@ -141,10 +144,19 @@ function(boost_url_setup_properties target)
     target_compile_definitions(${target} PRIVATE BOOST_URL_SOURCE)
     target_compile_options(${target} PUBLIC $<$<CXX_COMPILER_ID:MSVC>:/EHsc>)
 endfunction()
+
+if (BOOST_URL_MRDOCS_BUILD)
+    file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/mrdocs.cpp" "#include <boost/url.hpp>\n")
+    add_library(boost_url_mrdocs "${CMAKE_CURRENT_BINARY_DIR}/mrdocs.cpp")
+    boost_url_setup_properties(boost_url_mrdocs)
+    return()
+endif()
+
 add_library(boost_url ${BOOST_URL_HEADERS} ${BOOST_URL_SOURCES})
 add_library(Boost::url ALIAS boost_url)
 boost_url_setup_properties(boost_url)
 
+
 #-------------------------------------------------
 #
 # Tests
@@ -165,3 +177,5 @@ endif ()
 if (BOOST_URL_BUILD_EXAMPLES)
     add_subdirectory(example)
 endif ()
+
+

doc/mrdocs.yml

@@ -43,5 +43,26 @@ base-url: https://github.com/boostorg/url/blob/develop/include/ # boost/url/
 verbose: true
 multipage: true
 
-# BUILD_TESTING is required for header-only functionality to be extracted
-cmake: '-D BUILD_TESTING=ON -D BOOST_URL_BUILD_EXAMPLES=OFF'
+# The target for MrDocs simply includes all symbols defined in all
+# headers with the appropriate compilation options.
+# Nothing else should be included in the MrDocs configuration or 
+# would be useful to MrDocs.
+#
+# This single source file not only includes all symbols (the source
+# files do not collectively include all headers) but also makes MrDocs
+# run much faster than relying on the entire library.
+#
+# The time to extract the declarations went from ~8m6s to ~3s in our
+# experiments: a 162x speedup while including all symbols!
+#
+# In practice, this special target is simply emulating the
+# default behavior of the standardese tool with MrDocs, which
+# requires the user to clearly specify the targets via the
+# compilation database.
+#
+# The BOOST_URL_MRDOCS_BUILD=ON is the only option we usually need
+# here.
+# The other options are set just to ensure other targets are
+# ignored even if these options are set as ON in the cache.
+#
+cmake: '-D BOOST_URL_MRDOCS_BUILD=ON -D BOOST_URL_BUILD_FUZZERS=OFF -D BOOST_URL_BUILD_EXAMPLES=OFF -D BOOST_URL_BUILD_TESTS=OFF -D BUILD_TESTING=OFF'

include/boost/url.hpp

@@ -43,6 +43,7 @@
 #include <boost/url/segments_ref.hpp>
 #include <boost/url/segments_view.hpp>
 #include <boost/url/static_url.hpp>
+#include <boost/url/string_view.hpp>
 #include <boost/core/detail/string_view.hpp>
 #include <boost/url/url.hpp>
 #include <boost/url/url_base.hpp>