CXX-3068 Revert API docs to their initial state + cap to Doxygen 1.9.1

[eramongodb]

Warning

DO NOT OPEN THE "FILES CHANGED" TAB!!!

30945 files changed, 932833 insertions(+), 926358 deletions(-)

This PR has a HUGE diff! Avoid opening the Files Changed tab or individual commits on GitHub. Otherwise, your tab/browser may lag greatly! Recommend reviewing changes locally instead.

Summary

Resolves CXX-3068. Note the target branch is gh-pages, not master.

Reverts the state of every API subdirectory to their initial state + caps the latest Doxygen version used for generation to 1.9.1, matching the current version in the Doxyfile.

Recommend verifying changes locally rather than on GitHub.

Initial State

Prior to #1169 (CXX-3063), all API docs were regenerated with every release in their totality regardless of the version of the Doxygen binary being used at the time or its compatibility with the Doxyfile configuration file for the given release. This resulted in the API docs being (re)generated with thirteen different Doxygen versions over the course of their lifetime. The following table lists the Doxygen version used (when different from the version used to generate the docs prior), the date of the change, and the estimated C++ Driver version related to the change:

1.8.10  (2016-09-28) (r3.0.2)
1.8.9.1 (2016-12-13) (r3.1.0)
1.8.10  (2016-12-20) (r3.1.1)
1.8.13  (2017-07-12) (r3.1.2)
1.8.14  (2018-05-31) (r3.3.0)
1.8.13  (2018-10-01) (r3.4.0)
1.8.17  (2020-07-30) (r3.6.0)
1.8.20  (2020-11-03) (r3.6.1)
1.8.18  (2020-12-01) (r3.6.2)
1.8.20  (2021-06-03) (r3.6.4)
1.9.2   (2022-05-03) (r3.6.7)
1.8.17  (2022-09-30) (r3.7.0)
1.9.6   (2023-03-14) (r3.7.1)
1.9.1   (2023-06-06) (r3.7.2)
1.9.6   (2023-06-21) (r3.8.0)
1.9.8   (2023-10-05) (r3.8.1)
1.9.7   (2023-11-08) (r3.9.0)
1.9.1   (2024-02-23) (r3.10.0)
1.9.7   (2024-03-05) (r3.10.1)
1.9.1   (2024-06-25) (r3.10.2)

All docs are currently generated with 1.9.1 according to what was used in the latest release (r3.10.2). This PR's diff is relative to this current state.

The Doxyfile has only ever been explicitly (re)generated with a Doxygen version twice: with version 1.8.9.1 at time of creation (Jan 2015) and with version 1.9.1 by #1015 (Sep 2023) as a casual drive-by improvement without understanding its potential impact at the time. In ancient times, there was a doxygenConfig file, later renamed to etc/doxygen/config, but it is unclear what Doxygen version it was intended to be used with.

It is difficult to validate the appearance and contents of all API docs according to their evolution over the years with every regeneration. Therefore this PR proposes reverting most API doc pages to their initial state at time of creation regardless of whatever Doxygen version may have been used for their generation. This includes the legacy C++ Driver API doc pages, despite no explicit reference to them at this time.

An exception is made for docs generated with a Doxygen version newer than 1.9.1: they have been regenerated with 1.9.1 according to their initial state (including the state of the etc/apidocmenu.md file at time of creation) to avoid unverified changes which may have been introduced by even newer Doxygen version (i.e. the addition of dark theme support in 1.9.6 which drastically changes the appearance of the pages) and to (attempt to) synchronize with the current 1.9.1 Doxyfile (applicable to C++ Driver 3.9.0 and newer).

Therefore, the following API doc pages are regenerated with Doxygen 1.9.1:

• 3.6.7 (left as 1.9.2 due to normal appearance on manual inspection)
• 3.7.1 (was 1.9.6)
• 3.8.0 (was 1.9.6)
• 3.8.1 (was 1.9.8)
• 3.9.0 (was 1.9.7)
• 3.10.1 (was 1.9.7)

All others are reverted to their initial state at time of creation.

etc/apidocmenu.md

Important

Upon request, a followup ticket to implement this feature may be created if we want to continue supporting this feature (listing "latest" versions even in past API doc homepages). It would need to use a different mechanism than what was used prior (e.g. a more targeted update to each API doc's index.html page).

It is likely that API doc regeneration was largely motivated by the desire to keep the homepage updated with a list of latest releases, including those in the "future" relative to a given API doc. For example, this is the current homepage for the 3.0.0 docs (Jan 2016):

At the moment, this PR does not support this feature: old API docs list only the versions which were present at time of creation. The 3.0.0 docs are thus reverted by this PR to its original appearance:

Release Candidate Documentation

This PR takes this opportunity to delete API doc pages for release candidates, including any references to them in old API docs. This affects 3.1.0, 3.1.4, and 3.2.0. Only the pages for 3.6.0-rc0 were present (and are thus removed).

[kevinAlbs]

Upon request, a followup ticket to implement this feature may be created if we want to continue supporting this feature (listing "latest" versions even in past API doc homepages).

I would like to request. I expect users may stumble on old pages. Searching "mongocxx::collection" in Google page resulted in the page for 3.0.2 as the first result.

[eramongodb]

I would like to request.

Created and scheduled CXX-3081.

[eramongodb]

Rebase-merging this PR to scope and associate individual commits with their associated subdirectories.