CXX-3199 Generate API documentation with generated headers

[eramongodb]

Summary

Addresses CXX-3199.

Refactors the doxygen-current and doxygen-latest targets to generate API documentation pages using a full set of headers, including those which are generated by CMake during configuration (e.g. export.hpp).

Generated Headers

This PR effectively requires Doxygen be executed via the CMake targets doxygen-current (although it is really the docs_source_directory that is important). The docs_source_directory target takes advantage of the symmetric directory layout implemented by #1026 and raw-copies the <lib>/include and <lib>/lib directories into the same directory. This effectively merges the public and internal directory structure together into a single "install" directory which is parsed by Doxygen.

Important

The build/doxygen directory is now reserved for use by Doxygen so that this behavior is reliable regardless of the custom binary directory being used by the user.

Warning

This blindly copies the contents of the include and lib directories without any filters. If there are any stray .hpp header files in either directory, they will be blindly copied as well. This is not an issue for the doxygen-latest target which uses a temporary directory, but may cause some inconvenience for the doxygen-current target.

This permits Doxygen documentation comments to be embedded directly in the generated headers' input files, obviating the need to define "Group" pages to document non-existent header files. The headers can now be referenced directly (e.g. @ref bsoncxx/v_noabi/bsoncxx/config/export.hpp) and are listed under the Files page just like any other header.

To continue supporting the use of a custom Doxygen binary (to enforce an exact Doxygen version and corresponding generated output), the CMake FindDoxygen module is used to permit customization via the DOXYGEN_EXECUTABLE variable (use as a result variable is deprecated in favor of Doxygen::doxygen, but this variable is still used for the internal call to find_program()).

The following command thus generates the current API doc pages for local preview:

# Custom binary if needed.
cmake -S . -B <binary> -D DOXYGEN_EXECUTABLE=doxygen-1.12.0

# Generate API docs under build/docs/api/current.
cmake --build <binary-dir> --target doxygen-current

Latest API Docs

The generate-* Perl scripts are completely removed in favor of a Bash script to remove our toolchain dependency on Perl. Following #1169, the generate-latest-apidocs.pl effectively lost its purpose as the "generate the latest instead of generating all" script, since we no longer regenerate old doc pages. The generate-apidocs-from-tag.pl was only being used to implement the behavior of generate-latest-apidocs.pl and no longer used for any other purpose.

To avoid continuing to maintain Perl, both scripts are replaced with a straightforward Bash script that preserves only the minimum required behaviors from the old scripts. A temporary directory is used to clone a clean copy of the repository and checkout the relevant release tag whose source files are to be documented. sed is used to directly patch the Doxyfile with relevant version information and output path. CMake is called to generate the headers (via --target docs_source_directory) before running Doxygen manually to avoid confusing the current CMake project (which invokes --target doxygen-latest) and the CMake project in the temporary directory being used to generate the API documentation.

# For generate-latest-apidocs.sh.
export DOXYGEN_BINARY=doxygen-1.12.0

# To avoid downloading the C Driver.
export CMAKE_PREFIX_PATH=/path/to/c-driver/install

# Local repository.
cmake -S . -B build

# Generate API docs under build/docs/api/<latest>.
cmake --build build --target doxygen-latest