CXX-3063 deploy only the latest API docs during a release

[eramongodb]

Summary

Resolves CXX-3063.

This is the first in a series of PRs related to CXX-2827 which address issues and establishes patterns essential to upcoming changes in CXX-2745.

The goal of this PR is to open the path for Doxygen version upgrades and updates to the Doxyfile without fear of breaking old API docs.

Doxygen Version Check

The generated API documentation HTML pages are sensitive to the Doxygen version being used. However, there are no checks currently present to ensure consistency of the Doxygen version used during deployments. It is unknown what Doxygen version may have been used to generate the API docs for any given release. This means the API doc pages may have changed arbitrarily depending on the version of Doxygen used by the maintainer performing the deployment per release. (!!)

As an example, Doxygen 1.9.5 adds support for dark themes via a new HTML_COLORSTYLE option which defaults to AUTO_LIGHT. This has the effect of potentially rendering the pages in a "dark" style that is inconsistent with any prior releases (all use the LIGHT theme).

Many similar unexpected changes may occur when using a different Doxygen versions than is expected.

This PR adds this essential version check to ensure we are aware of the Doxygen version being used during generation and deployment. This is checked by the etc/generate-apidocs-from-tag.pl script according to the $doxygen_version_required variable. The $DOXYGEN_BINARY environment variable is supported as a customization point when a custom Doxygen installation needs to be used to satisfy the version requirement.

Deploy ONLY Latest API Docs Per Release

This is a critical change which avoids the total regeneration of old API docs using the current Doxygen version regardless of Doxyfile compatibility. Prior updates to the Doxyfile (e.g. #1015) or the choice of Doxygen binary used during deployment did not take this into account. Ensuring only the latest API docs are deployed with a given Doxygen version per deployment permits us to update our required Doxygen version without fear or risk of breaking old API docs (they should remain untouched). As each versioned API docs directory is generated in isolation as its own set of webpages, stability is not expected to be a concern.

Note

This means the table of documentation versions available for an old API docs page may not list newer available versions. This is considered a reasonable compromise. We can consider manually inserting a link to the latest API docs page (current) to "return" to the newest version currently available from old API docs pages for convenience.

The old etc/generate-all-apidocs.pl is renamed to etc/generate-latest-apidocs.pl and repurposed to generate only the latest API docs as specified by the new $LATEST_DOC_TAG variable. The doxygen-deploy CMake target now depends only on the new doxygen-latest target (which generates the latest API docs), which is then rsync'd (without --delete!) into the gh-pages branch's api/ directory. The result is that for each deployment, only a single new mongocxx-<latest-release-tag> directory should be added under the api/ directory in the gh-pages branch. Unlike prior deployments, the contents of prior directories (old API docs) are no longer updated.

Old API Docs on the gh-pages Branch

The gh-pages branch may subsequently need to be audited and updated to revert the contents of old API doc directories to their original state, as up to this point, every CXX Driver release has regenerated and redeployed all API docs pages with whatever Doxygen binary was being used at time of deployment (which has also unnecessarily, significantly bloated the volume of git diffs being tracked by the branch).

Miscellaneous Improvements

• The s{}{} Perl syntax appears to confuse VS Code's syntax highlighter. Replaced with the equivalent s// syntax.
• Improved git clone performance during deployment by adding the --filter=blob:none flag.
• etc/generate-apidocs-from-tag.pl uses build/tmp-repo for work, but etc/deploy-to-ghpages.pl uses system /tmp. Change the latter to also use build/tmp-repo for consistency.

[kevinAlbs]

LGTM. I very much support isolating generation of API docs to the latest version.

[rcsanchez97]

LGTM