From e783956c8c9561f0402bdcf0e4f6c2205c5995e3 Mon Sep 17 00:00:00 2001
From: Ezra Chung <ezra.chung@mongodb.com>
Date: Wed, 17 Jul 2024 11:37:06 -0500
Subject: [PATCH 1/6] releasing: add warning for `git clean -dfx` command

---
 etc/releasing.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/etc/releasing.md b/etc/releasing.md
index 425e1c4541..6d1beb33e4 100644
--- a/etc/releasing.md
+++ b/etc/releasing.md
@@ -568,6 +568,9 @@ command -V doxygen hugo
 
 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

From 4c0281a5af5d2d6b06ac0f81330865a41d61111b Mon Sep 17 00:00:00 2001
From: Ezra Chung <ezra.chung@mongodb.com>
Date: Wed, 17 Jul 2024 11:37:05 -0500
Subject: [PATCH 2/6] perl: fix syntax highlighting errors in
 etc/generate-apidocs-from-tag.pl

---
 etc/generate-apidocs-from-tag.pl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/etc/generate-apidocs-from-tag.pl b/etc/generate-apidocs-from-tag.pl
index 35833e0616..8b9647f32c 100755
--- a/etc/generate-apidocs-from-tag.pl
+++ b/etc/generate-apidocs-from-tag.pl
@@ -74,7 +74,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

From ffd4559877a292f2f225cc63cdca0b1ecf6ab640 Mon Sep 17 00:00:00 2001
From: Ezra Chung <ezra.chung@mongodb.com>
Date: Wed, 17 Jul 2024 11:37:06 -0500
Subject: [PATCH 3/6] releasing: speed up clone of gh-pages repo during
 deployment

---
 etc/deploy-to-ghpages.pl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/etc/deploy-to-ghpages.pl b/etc/deploy-to-ghpages.pl
index 621e9c878c..e34fd08bc9 100755
--- a/etc/deploy-to-ghpages.pl
+++ b/etc/deploy-to-ghpages.pl
@@ -60,7 +60,7 @@ sub main {
     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/);

From 355e5a05525391193fc72550ed89b26bb18e8219 Mon Sep 17 00:00:00 2001
From: Ezra Chung <ezra.chung@mongodb.com>
Date: Wed, 17 Jul 2024 11:37:06 -0500
Subject: [PATCH 4/6] releasing: use local build/tmp-repo instead of system
 /tmp for deployment

---
 etc/deploy-to-ghpages.pl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/etc/deploy-to-ghpages.pl b/etc/deploy-to-ghpages.pl
index e34fd08bc9..57df47b9c6 100755
--- a/etc/deploy-to-ghpages.pl
+++ b/etc/deploy-to-ghpages.pl
@@ -56,7 +56,8 @@ 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.

From 8f26f90f2363dd40836c41e35736b39944406530 Mon Sep 17 00:00:00 2001
From: Ezra Chung <ezra.chung@mongodb.com>
Date: Wed, 17 Jul 2024 11:37:05 -0500
Subject: [PATCH 5/6] CXX-3063 require Doxygen version 1.9.1

---
 etc/generate-apidocs-from-tag.pl | 24 ++++++++++++++++++++++--
 etc/releasing.md                 |  7 +++++--
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/etc/generate-apidocs-from-tag.pl b/etc/generate-apidocs-from-tag.pl
index 8b9647f32c..90479c27d8 100755
--- a/etc/generate-apidocs-from-tag.pl
+++ b/etc/generate-apidocs-from-tag.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 = @_;
@@ -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};
 }
-
diff --git a/etc/releasing.md b/etc/releasing.md
index 6d1beb33e4..1f99abe7b9 100644
--- a/etc/releasing.md
+++ b/etc/releasing.md
@@ -566,6 +566,9 @@ 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]
@@ -577,13 +580,13 @@ Configure CMake using `build` as the binary directory. Leave all other configura
 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 all versioned Doxygen docs by building the `doxygen-all` target (this command DOES checks for the required Doxygen version):
 
 ```bash
 cmake --build build --target doxygen-all

From 5f29bf444685b50afab3d1e16df4ba130fec609c Mon Sep 17 00:00:00 2001
From: Ezra Chung <ezra.chung@mongodb.com>
Date: Wed, 17 Jul 2024 11:37:06 -0500
Subject: [PATCH 6/6] CXX-3063 commit ONLY latest API docs to gh-pages during
 release

---
 CMakeLists.txt                 |  6 +--
 etc/deploy-to-ghpages.pl       |  3 +-
 etc/generate-all-apidocs.pl    | 77 ----------------------------------
 etc/generate-latest-apidocs.pl | 22 ++++++++++
 etc/releasing.md               |  6 +--
 5 files changed, 29 insertions(+), 85 deletions(-)
 delete mode 100755 etc/generate-all-apidocs.pl
 create mode 100755 etc/generate-latest-apidocs.pl

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 28c421b020..3204a5eb35 100644
--- a/CMakeLists.txt
+++ b/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 git@github.com:mongodb/mongo-cxx-driver
     VERBATIM
diff --git a/etc/deploy-to-ghpages.pl b/etc/deploy-to-ghpages.pl
index 57df47b9c6..9fef7131d5 100755
--- a/etc/deploy-to-ghpages.pl
+++ b/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/"
     );
@@ -105,4 +105,3 @@ sub DESTROY {
     my $self = shift;
     $self->{demolish}->() if $self->{demolish};
 }
-
diff --git a/etc/generate-all-apidocs.pl b/etc/generate-all-apidocs.pl
deleted file mode 100755
index 31e9f6a14c..0000000000
--- a/etc/generate-all-apidocs.pl
+++ /dev/null
@@ -1,77 +0,0 @@
-#!/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 @DOC_TAGS = qw(
-  legacy-0.8.0
-  legacy-0.9.0
-  legacy-0.10.0
-  legacy-0.11.0
-  legacy-1.0.0
-  legacy-1.0.1
-  legacy-1.0.2
-  legacy-1.0.3
-  legacy-1.0.4
-  legacy-1.0.5
-  legacy-1.0.6
-  legacy-1.0.7
-  legacy-1.1.0
-  legacy-1.1.1
-  legacy-1.1.2
-  r3.0.0
-  r3.0.1
-  r3.0.2
-  r3.0.3
-  r3.1.0
-  r3.1.1
-  r3.1.2
-  r3.1.3
-  r3.1.4
-  r3.2.0
-  r3.2.1
-  r3.3.0
-  r3.3.1
-  r3.3.2
-  r3.4.0
-  r3.4.1
-  r3.4.2
-  r3.5.0
-  r3.5.1
-  r3.6.0-rc0
-  r3.6.0
-  r3.6.1
-  r3.6.2
-  r3.6.3
-  r3.6.4
-  r3.6.5
-  r3.6.6
-  r3.6.7
-  r3.7.0
-  r3.7.1
-  r3.7.2
-  r3.8.0
-  r3.8.1
-  r3.9.0
-  r3.10.0
-  r3.10.1
-  r3.10.2
-);
-
-sub main {
-    for my $ref ( @DOC_TAGS ) {
-        _try_run("etc/generate-apidocs-from-tag.pl", $ref);
-    }
-}
-
-main();
diff --git a/etc/generate-latest-apidocs.pl b/etc/generate-latest-apidocs.pl
new file mode 100755
index 0000000000..f85eab74d0
--- /dev/null
+++ b/etc/generate-latest-apidocs.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();
diff --git a/etc/releasing.md b/etc/releasing.md
index 1f99abe7b9..21d9af0fe2 100644
--- a/etc/releasing.md
+++ b/etc/releasing.md
@@ -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:
 
@@ -586,10 +586,10 @@ Test generating Hugo and Doxygen docs locally by building the `docs` target (thi
 cmake --build build --target docs
 ```
 
-Test generating all versioned Doxygen docs by building the `doxygen-all` target (this command DOES checks for the required Doxygen version):
+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.