CXX-3081 Keep API doc index pages up-to-date with each release

[eramongodb]

Summary

Resolves CXX-3081. Followup to #1169 and #1174.

This PR adds a new script which is invoked during API doc deployment which patches the index pages of all prior API docs to match that of the latest API doc. This permits each API doc to have an up-to-date list of C++ Driver releases, links to resources, and possibly other information (such as announcements).

Index Page Contents

Regardless of Doxygen version and API doc version, the following patterns were observed:

• There is an index.html file at the top-level directory of each API doc directory corresponding to the "Main Page" for each API doc.
• The index.html file contains a <div class="contents">...</div> corresponding to main page contents.
• The title, headers, footers, and other elements specific to each API doc are not members of the contents element.

Therefore, this PR proposes the "contents" element of each index page be directly substituted with that of the latest API doc with each deployment. This ensures a direct and targeted means of keeping the home page of old API docs up-to-date with the contents of etc/apidocmenu.md for each release while minimizing the risk of breaking old API doc pages due to Doxygen version inconsistencies/incompatibilities. Recommend examining the patch commit (not the format commit) in #1181 for a demonstration of expected ehavior.

etc/patch-apidocs-index-pages.py

This script is now invoked as part of the doxygen-deploy command. An APIDOCSPATH environment variable is used to specify the api/ directory under which API docs are located. This env var may be used when manually invoking the script for testing purposes.

This script is designed to fail fast, fail hard should it encounter any unexpected situations to avoid risk of unintentional modifications to unrelated files and avoid deploying broken pages.

The Beautiful Soup Python library is selected for purposes of formatting and editing HTML. In particular, its ability to easily find an HTML element by class and directly replace the contents of an HTML element perfectly fulfills the needs of this PR.

The script also ensures all index pages (including the latest) are formatted per .prettify(formatter="html"). This will make future patches to the index pages easier to inspect and review for correctness. Note: using the html5 formatter was considered but dropped due to it applying more changes to the HTML than what appeared to be minimally necessary.

An example of the expected script output:

Patching API docs in: build/tmp-repo/Jfa6dNfcZ5/api
Finding API docs...
 - Skipping: mongocxx-3.11.0-example
Finding API docs... done.
 - Found 51 API docs: legacy-0.8.0 ... mongocxx-3.10.2
Searching for index pages...
Searching for index pages... done.
 - Found 51 index pages within 51 API docs.
 - Using mongocxx-3.10.2 as the latest API doc.
Formatting latest index page...
Formatting latest index page... done.
Extracting latest index page contents...
Extracting latest index page contents... done.
Replacing contents of 50 index pages...
Replacing contents of 50 index pages... done.

Drive-By Improvements

• Replace jira @ ... with jira==3.5.2 which contains the required patch in prior comment.
• Fixed links to the MongoDB C++ Driver documentation pages (under cpp/cpp-driver, not cpp/drivers; did this change at some point?).
• Clarify expectation of contents of build/docs/api in release instructions. doxygen-deploy depends on doxygen-latest so it is easier to simply start with a clean slate after reviewing the correctness of generated API doc.

[kevinAlbs]

LGTM. The drive-by link fixes, and consistent formatting changes are also appreciated.

[kevinAlbs]

Suggested change

	# Sort by legacy vs. modern, then by SemvVer. Example:
	# Sort by legacy vs. modern, then by SemVer. Example: