CXX-3097 add patch-apidocs-current-redirects.py

[eramongodb]

Summary

Related to CXX-3097. See also #1239.

Adds a new patch script to the page deployment process which inserts redirect routines to API doc pages such that navigating to an /api/current page automatically redirects the user to the canonical /api/mongocxx-<version> page.

patch-apidocs-current-redirects.py

The new patch script behaves in a similar way to the patch-apidocs-index-pages.py script introduced in #1180. The APIDOCSPATH=/path/to/api environment variable is used to describe the location of the /api directory, under which mongocxx-<version> API doc directories are present. The latest API doc directory is identified by sorting the directory names by version.

Unlike patch-apidocs-index-pages.py, BeautifulSoup4 is not used to parse and modify the HTML contents due to its implicit attribute-sorting behavior generating far more diffs than necessary. No straightforward way to disable this behavior while preserving the existing formatting of the HTML files (without "prettifying" its contents) could be found. Therefore, simple line parsing and index-based line insertion is used instead. See #1239 for the results of the patch applied to the current latest API doc pages (for 3.11.0).

The large number of files which need to be processed (+1K) motivated the use of concurrent.futures.ProcessPoolExecutor to achieve reasonably fast runtime performance.

The new patch script is automatically invoked by deploy-to-ghpages.pl immediately after invocation of the patch-apidocs-index-pages.py script.

Release instructions are updated to include adding an entry to the sitemap index for the newly-deployed API doc pages and updating <lastmod> to communicate the update to search engines. See #1239 for details.

Miscellaneous

The icon for the API Documentation page link is updated for visual consistency.

Before:

After:

Additionally the now-unused /categories and /tags directories are no longer generated by Hugo (per disableKinds) to avoid stepping over the new redirect pages introduced in #1239.

[eramongodb]

Drive-by improvements while inspecting deploy script behavior:

• Fix broken links #1071 added a trailing / to the homepage variables in theme.toml, which leads to double-slashes in Hugo generated URLs (primarily concerns legacy pages, but also the root index.html file). Removed this trailing slash.
• Added . to STRIP_FROM_PATH (+ STRIP_FROM_INC_PATH for consistency) to avoid leaking local directory info in anchor IDs in Doxygen generated files (primarily concerns the apidocmenu.md file).

[kevinAlbs]

LGTM with a comment fix. I like the use of the patch tag to prevent double patching.

[ghost]

LGTM, this looks like it should be a big improvement for usability.

In an ideal world I'd really want to find a more efficient way to do the redirect, and a way to avoid repeating the site's base URI in so many places; but given all the constraints we're under the JavaScript does seem best.

It's unclear to me why we need to track whether the patch has been applied using a separate token. Could the 'patch-tag' actually just be 'window.location.href.replace' (or the whole line containing it)?

[eramongodb]

It's unclear to me why we need to track whether the patch has been applied using a separate token. Could the 'patch-tag' actually just be 'window.location.href.replace' (or the whole line containing it)?

It could, but I opted to insert a "named" tag that identifies the origins of where the inserted code block comes from (not part of regular Doxygen output + mentions the name of the script which generated it) for better traceability (e.g. grepping, git log, etc.). The double-patch prevention check is just a bonus that helps with local development + possibly help reduce the consequences of incorrect patching during a release.