CXX-3199 Generate API documentation with generated headers

CMakeLists.txt

@@ -283,20 +283,41 @@ add_custom_target(hugo-deploy
     VERBATIM
 )
 
-add_custom_target(docs_dir_current
+add_custom_target(docs_source_directory
+    VERBATIM
+
+    # Clear any existing files in the target directory.
+    COMMAND ${CMAKE_COMMAND} -E remove_directory
+        ${MONGO_CXX_DRIVER_SOURCE_DIR}/build/doxygen/install
+
+    # Manually "install" all headers without requiring compilation.
+    COMMAND ${CMAKE_COMMAND} -E copy_directory
+        ${MONGO_CXX_DRIVER_SOURCE_DIR}/src/bsoncxx/include
+        ${MONGO_CXX_DRIVER_BINARY_DIR}/src/bsoncxx/lib
+        ${MONGO_CXX_DRIVER_SOURCE_DIR}/build/doxygen/install/include
+    COMMAND ${CMAKE_COMMAND} -E copy_directory
+        ${MONGO_CXX_DRIVER_SOURCE_DIR}/src/mongocxx/include
+        ${MONGO_CXX_DRIVER_BINARY_DIR}/src/mongocxx/lib
+        ${MONGO_CXX_DRIVER_SOURCE_DIR}/build/doxygen/install/include
+)
+
+add_custom_target(docs_target_directory
     COMMAND ${CMAKE_COMMAND} -E make_directory docs/api/current
 )
 
+# Set `DOXYGEN_EXECUTABLE` to specify the full path to a custom Doxygen binary.
+find_package(Doxygen 1.12.0 EXACT QUIET)
+
 add_custom_target(doxygen-current
-    DEPENDS docs_dir_current
+    DEPENDS Doxygen::doxygen docs_source_directory docs_target_directory
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-    COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile
+    COMMAND Doxygen::doxygen
     VERBATIM
 )
 
 add_custom_target(doxygen-latest
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-    COMMAND etc/generate-latest-apidocs.pl
+    COMMAND etc/generate-latest-apidocs.sh
     VERBATIM
 )
 

Doxyfile

@@ -181,8 +181,7 @@ FULL_PATH_NAMES        = YES
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
 STRIP_FROM_PATH        = . \
-                         src/bsoncxx/include \
-                         src/mongocxx/include
+                         build/doxygen/install/include
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -192,8 +191,7 @@ STRIP_FROM_PATH        = . \
 # using the -I flag.
 
 STRIP_FROM_INC_PATH    = . \
-                         src/bsoncxx/include \
-                         src/mongocxx/include
+                         build/doxygen/install/include
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
@@ -836,7 +834,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
@@ -943,8 +941,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src/bsoncxx/include \
-                         src/mongocxx/include \
+INPUT                  = build/doxygen/install/include \
                          etc/apidocmenu.md
 
 # This tag can be used to specify the character encoding of the source files
@@ -2398,10 +2395,7 @@ SEARCH_INCLUDES        = YES
 # RECURSIVE has no effect here.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           = src/bsoncxx/include/bsoncxx/v_noabi \
-                         src/mongocxx/include/mongocxx/v_noabi \
-                         src/bsoncxx/include \
-                         src/mongocxx/include
+INCLUDE_PATH           = build/doxygen/install/include
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the

etc/generate-latest-apidocs.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# generate-latest-apidocs.sh
+#
+# Usage:
+#   ./etc/generate-latest-apidocs.sh
+#
+# This script is meant to be run from the project root directory.
+
+set -o errexit
+set -o pipefail
+
+LATEST_VERSION="4.0.0"
+DOXYGEN_VERSION_REQUIRED="1.12.0"
+
+# Permit using a custom Doxygen binary.
+: "${DOXYGEN_BINARY:=doxygen}"
+
+command -v git >/dev/null
+command -v mktemp >/dev/null
+command -v sed >/dev/null
+
+if [[ ! -d build ]]; then
+  echo "missing build directory: this script must be run from the project root directory" 1>&2
+  exit 1
+fi
+
+# Validate Doxygen version.
+doxygen_version="$("${DOXYGEN_BINARY:?}" -v | perl -lne 'print $1 if m/^(\d+\.\d+\.\d+).*$/')"
+if [[ "${doxygen_version:-}" != "${DOXYGEN_VERSION_REQUIRED:?}" ]]; then
+    echo "${DOXYGEN_BINARY} version ${doxygen_version:-"unknown"} does not equal ${DOXYGEN_VERSION_REQUIRED:?}" 1>&2
+    exit 1
+fi
+
+working_dir="$(pwd)"
+apidocpath="${working_dir:?}/build/docs/api/mongocxx-${LATEST_VERSION:?}"
+
+# Use a temporary directory for the following operations.
+tmpdir="$(mktemp -d)"
+trap "rm -rf \"${tmpdir}\"" EXIT
+
+mkdir -p "${apidocpath:?}"
+
+# Use a clean copy of the repository.
+git clone -q -c advice.detachedHead=false -b "v${LATEST_VERSION}" . "${tmpdir}"
+
+cd "${tmpdir:?}"
+
+# Update the Doxyfile configuration file:
+#  - set OUTPUT_DIRECTORY to `build/docs/api/mongocxx-<version>`.
+#  - set PROJECT_NUMBER to `<version>`.
+sed -i \
+  -e "s|^OUTPUT_DIRECTORY\s*=\s*.*$|OUTPUT_DIRECTORY = ${apidocpath:?}|g" \
+  -e "s|^PROJECT_NUMBER\s*=\s*.*$|PROJECT_NUMBER = ${LATEST_VERSION:?}|g" \
+  Doxyfile
+
+# Generate API documentation.
+(
+    set -o xtrace
+
+    cmake -S . -B build -D "DOXYGEN_EXECUTABLE=${DOXYGEN_BINARY:?}" --log-level=WARNING
+    cmake --build build --target docs_source_directory
+    "${DOXYGEN_BINARY:?}"
+)

etc/releasing.md

@@ -661,7 +661,7 @@ Example (using Jira syntax formatting):
 > [!NOTE]
 > Some of these commands may take a while to complete.
 
-Set `$LATEST_DOC_TAG` in `etc/generate-latest-apidocs.pl` to the latest release tag.
+Set `$LATEST_VERSION` in `etc/generate-latest-apidocs.sh` to the latest release version.
 
 Change the version number for `SITEMAP_URL` in `Doxyfile` to the latest release version.
 
@@ -678,7 +678,7 @@ command -V doxygen hugo
 ```
 
 > [!IMPORTANT]
-> The required Doxygen version is defined in `etc/generate-apidocs-from-tag.pl` as `$doxygen_version_required`. If not already present, download the required version from [Doxygen Releases](https://www.doxygen.nl/download.html). Use the `DOXYGEN_BINARY` environment variable to override the default `doxygen` command with a path to a specific Doxygen binary.
+> The required Doxygen version is defined in `etc/generate-latest-apidocs.sh` as `$DOXYGEN_VERSION_REQUIRED`. If not already present, download the required version from [Doxygen Releases](https://www.doxygen.nl/download.html). Use the `DOXYGEN_BINARY` environment variable to override the default `doxygen` command with a path to a specific Doxygen binary.
 
 Run `git clean -dfx` to restore the repository to a clean state.