CXX-3199 Generate API documentation with generated headers (#1301)

Author: eramongodb

CMakeLists.txt

@@ -283,20 +283,33 @@ add_custom_target(hugo-deploy
     VERBATIM
 )
 
-add_custom_target(docs_dir_current
-    COMMAND ${CMAKE_COMMAND} -E make_directory docs/api/current
+add_custom_target(doxygen-install-headers
+    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(doxygen-current
-    DEPENDS docs_dir_current
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-    COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile
+    COMMAND ${CMAKE_COMMAND} -E env DOXYGEN_USE_CURRENT=1 etc/generate-latest-apidocs.sh
     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-apidocs-from-tag.pl

@@ -0,0 +1,80 @@
+#!/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}"
+
+# Use the current repository instead of a clean temporary repository.
+: "${DOXYGEN_USE_CURRENT:=0}"
+
+# Permit using any Doxygen version.
+: "${DOXYGEN_ANY_VERSION:=0}"
+
+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
+  if [[ "${DOXYGEN_ANY_VERSION:?}" == 1 ]]; then
+    echo "using ${DOXYGEN_BINARY:?} version ${doxygen_version:-"unknown"} which does not equal ${DOXYGEN_VERSION_REQUIRED:?}" 1>&2
+  else
+    echo "${DOXYGEN_BINARY} version ${doxygen_version:-"unknown"} does not equal ${DOXYGEN_VERSION_REQUIRED:?}" 1>&2
+    exit 1
+  fi
+fi
+
+working_dir="$(pwd)"
+apidocspath="${working_dir:?}/build/docs/api"
+
+if [[ "${DOXYGEN_USE_CURRENT:?}" == 1 ]]; then
+  # Use the current repository's build directory.
+  output_directory="${apidocspath:?}/current"
+  scratch_dir="$(pwd)"
+else
+  # Use a clean copy of the repository.
+  output_directory="${apidocspath:?}/mongocxx-${LATEST_VERSION:?}"
+  scratch_dir="$(mktemp -d)"
+  trap 'rm -rf "${scratch_dir:?}"' EXIT
+
+  git clone -q -c advice.detachedHead=false -b "r${LATEST_VERSION}" . "${scratch_dir:?}"
+
+  # 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 = ${output_directory:?}|g" \
+    -e "s|^PROJECT_NUMBER\s*=\s*.*$|PROJECT_NUMBER = ${LATEST_VERSION:?}|g" \
+    "${scratch_dir:?}/Doxyfile"
+fi
+
+mkdir -p "${output_directory:?}"
+
+# Generate API documentation.
+(
+  cd "${scratch_dir:?}"
+
+  set -o xtrace
+
+  cmake -S . -B build --log-level=WARNING
+  cmake --build build --target doxygen-install-headers
+  "${DOXYGEN_BINARY:?}"
+)