CXX-3063 deploy only the latest API docs during a release (#1169)

* releasing: add warning for `git clean -dfx` command

* perl: fix syntax highlighting errors in etc/generate-apidocs-from-tag.pl

* releasing: speed up clone of gh-pages repo during deployment

* releasing: use local build/tmp-repo instead of system /tmp for deployment

* CXX-3063 require Doxygen version 1.9.1

* CXX-3063 commit ONLY latest API docs to gh-pages during release

Author: eramongodb

CMakeLists.txt

@@ -309,14 +309,14 @@ add_custom_target(doxygen-current
     VERBATIM
 )
 
-add_custom_target(doxygen-all
+add_custom_target(doxygen-latest
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-    COMMAND etc/generate-all-apidocs.pl
+    COMMAND etc/generate-latest-apidocs.pl
     VERBATIM
 )
 
 add_custom_target(doxygen-deploy
-    DEPENDS doxygen-all
+    DEPENDS doxygen-latest
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
     COMMAND etc/deploy-to-ghpages.pl --doxygen [email protected]:mongodb/mongo-cxx-driver
     VERBATIM

etc/deploy-to-ghpages.pl

@@ -37,7 +37,7 @@ sub _doxygen_rsync {
     my $tmpdir = shift;
     my @filters = ( '- /current', '- /mongocxx-v3', '- /legacy-v1' );
     _try_run(
-        qw{rsync -Cavz --delete},
+        qw{rsync -Cavz},
         ( map { ; '--filter' => $_ } @filters ),
         "build/docs/api/", "$tmpdir/api/"
     );
@@ -56,11 +56,12 @@ sub main {
     my $orig_dir = getcwd();
 
     # Create tempdir to store copy of repo.
-    my $tmp = tempdir( DIR => "/tmp", CLEANUP => 1 );
+    _try_run("mkdir", "-p", "build/tmp-repo");
+    my $tmp = tempdir( DIR => "build/tmp-repo", CLEANUP => 1 );
     my $tmpdir = realpath("$tmp");
 
     # Clone current repo to tempdir and checkout gh-pages branch.
-    _try_run( qw/git clone/, $source_repo, $tmpdir );
+    _try_run( qw/git clone --filter=blob:none/, $source_repo, $tmpdir );
     {
         my $guard = _pushd($tmpdir);
         _try_run(qw/git checkout gh-pages/);
@@ -104,4 +105,3 @@ sub DESTROY {
     my $self = shift;
     $self->{demolish}->() if $self->{demolish};
 }
-

etc/generate-all-apidocs.pl

@@ -9,6 +9,13 @@
 use File::Temp qw/tempdir/;
 use List::Util qw/first/;
 
+# The required Doxygen version.
+# The generated results are sensitive to the release version.
+our $doxygen_version_required = "1.9.1";
+
+# Allow specifying a custom Doxygen binary via the `$DOXYGEN_BINARY` environment variable.
+our $doxygen_binary = $ENV{DOXYGEN_BINARY} || "doxygen";
+
 # system() wrapper to die with an error if a command fails.
 sub _try_run {
     my @command = @_;
@@ -74,7 +81,7 @@ sub _parse_doxygen_config {
         next if substr($line,0,1) eq '#';
         next unless $line =~ /\S.*=/;
         # Join lines ending in backslash.
-        while ( $line =~ s{\\\n\z}{} ) {
+        while ( $line =~ s/\\\n\z// ) {
             $line .= " " . <$fh>;
         }
         # Save full line under the assigned key
@@ -84,6 +91,17 @@ sub _parse_doxygen_config {
     return \%config;
 }
 
+# Enforce a compatible Doxygen version.
+sub _check_doxygen_version {
+    die "Failed to parse Doxygen version from output of `$doxygen_binary -v`"
+        unless `$doxygen_binary -v` =~ /^(\d+\.\d+\.\d+).*$/;
+
+    my $doxygen_version = $1; # Strip unneeded content.
+
+    die "Detected Doxygen version $doxygen_version does not match required version $doxygen_version_required"
+        unless $doxygen_version =~ /^$doxygen_version_required/
+}
+
 sub main {
     my $gitref = shift @ARGV;
 
@@ -134,8 +152,11 @@ sub main {
         qq[HTML_EXTRA_STYLESHEET = "$orig_dir/etc/doxygen-extra.css"\n],
     );
 
+    # Ensure up-to-date Doxygen version.
+    _check_doxygen_version();
+
     # Run doxygen
-    _try_run('doxygen', "$tmpdir/Doxyfile");
+    _try_run("$doxygen_binary", "$tmpdir/Doxyfile");
 }
 
 main();
@@ -152,4 +173,3 @@ sub DESTROY {
     my $self = shift;
     $self->{demolish}->() if $self->{demolish};
 }
-

etc/generate-apidocs-from-tag.pl

@@ -0,0 +1,22 @@
+#!/usr/bin/env perl
+use v5.14;
+use strict;
+use warnings;
+use utf8;
+use open qw/:std :utf8/;
+
+# system() wrapper to die with an error if a command fails.
+sub _try_run {
+    my @command = @_;
+    say "> Running: @command";
+    system(@command);
+    die "Error running '@command" if $?;
+}
+
+my $LATEST_DOC_TAG = "r3.10.2";
+
+sub main {
+    _try_run("etc/generate-apidocs-from-tag.pl", $LATEST_DOC_TAG);
+}
+
+main();

etc/generate-latest-apidocs.pl

@@ -552,7 +552,7 @@ Example (using Jira syntax formatting):
 > [!NOTE]
 > Some of these commands may take a while to complete.
 
-Add the new release to the `@DOC_TAGS` array in `etc/generate-all-apidocs.pl`.
+Set `$LATEST_DOC_TAG` in `etc/generate-latest-apidocs.pl` to the latest release tag.
 
 Commit these changes to the `post-release-changes` branch:
 
@@ -566,24 +566,30 @@ Ensure `doxygen` and `hugo` are locally installed and up-to-date.
 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.
+
 Run `git clean -dfx` to restore the repository to a clean state.
 
+> [!WARNING]
+> Do NOT run `git clean -dfx` in your local development repository, as it may delete your local development files present in the repository (even if excluded)! Only run this in the command in the separate repository being used for this release!
+
 Configure CMake using `build` as the binary directory. Leave all other configuration variables as their default.
 
 ```bash
 cmake -S . -B build
 ```
 
-Test generating Hugo docs locally by building the `docs` target:
+Test generating Hugo and Doxygen docs locally by building the `docs` target (this command DOES NOT check for the required Doxygen version):
 
 ```bash
 cmake --build build --target docs
 ```
 
-Test generating Doxygen docs by building the `doxygen-all` target:
+Test generating the latest versioned Doxygen docs by building the `doxygen-latest` target (this command DOES checks for the required Doxygen version):
 
 ```bash
-cmake --build build --target doxygen-all
+cmake --build build --target doxygen-latest
 ```
 
 Verify that the `build/docs/api/mongocxx-X.Y.Z` directory is present and populated.