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 621e9c878c..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/" ); @@ -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}; } - 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-apidocs-from-tag.pl b/etc/generate-apidocs-from-tag.pl index 35833e0616..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 = @_; @@ -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}; } - 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 425e1c4541..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: @@ -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.