Update Sphinx, Theming, and Faster Builds (#1354)

* Fix parallel Sphinx builds when building man output
* Don't use vendored theme
* Remove vendored theming
* Update SphinxBuild.cmake for newer CMake and to use parallel builds
* Update Sphinx version
* Fix: Documentation version was garbled by debug output
* Use the dirhtml builder:

Generates "prettier" URLs. To support the old URLs, also generate HTML
files that cause a redirect to the new URLs.

* Use the "furo" theme.

Author: vector-of-bool

.evergreen/scripts/build-docs.sh

@@ -10,8 +10,8 @@ CMAKE=$(find_cmake_latest)
 grep "á" NEWS > /dev/null || (echo "NEWS file appears to have lost its UTF-8 encoding?" || exit 1)
 
 debug "Calculating release version..."
-python build/calc_release_version.py -d >VERSION_CURRENT
-python build/calc_release_version.py -d -p >VERSION_RELEASED
+python build/calc_release_version.py >VERSION_CURRENT
+python build/calc_release_version.py -p >VERSION_RELEASED
 
 build_dir=$MONGOC_DIR/_build/for-docs
 "$CMAKE" -S "$MONGOC_DIR" -B "$build_dir" \

.evergreen/scripts/debian_package_build.sh

@@ -43,7 +43,7 @@ export DEBOOTSTRAP_DIR=`pwd`/debootstrap.git
 sudo -E ./debootstrap.git/debootstrap unstable ./unstable-chroot/ http://cdn-aws.deb.debian.org/debian
 cp -a mongoc ./unstable-chroot/tmp/
 sudo chroot ./unstable-chroot /bin/bash -c "(\
-  apt-get install -y build-essential git-buildpackage fakeroot debhelper cmake libssl-dev pkg-config python3-sphinx zlib1g-dev libsasl2-dev libsnappy-dev libzstd-dev libmongocrypt-dev libjs-mathjax libutf8proc-dev && \
+  apt-get install -y build-essential git-buildpackage fakeroot debhelper cmake libssl-dev pkg-config python3-sphinx zlib1g-dev libsasl2-dev libsnappy-dev libzstd-dev libmongocrypt-dev libjs-mathjax libutf8proc-dev furo && \
   chown -R root:root /tmp/mongoc && \
   cd /tmp/mongoc && \
   git clean -fdx && \

.gitignore

@@ -19,7 +19,6 @@ CPackSourceConfig.cmake
 CTestTestfile.cmake
 _build/
 dist_manifest.txt
-Makefile
 test-results.json
 VERSION_CURRENT
 VERSION_RELEASED

build/cmake/SphinxBuild.cmake

@@ -21,14 +21,13 @@ function (sphinx_build_html target_name doc_dir)
    ProcessorCount (NPROCS)
 
    set (SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
+   set (doctrees_dir "${SPHINX_HTML_DIR}.doctrees")
 
-   file (GLOB doc_rsts RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
-
-   foreach (rst IN LISTS doc_rsts)
-      # Every .rst builds a corresponding .html
-      string (REGEX REPLACE "^([^.]+)\.rst$" "html/\\1.html" html ${rst})
-      list (APPEND doc_htmls ${html})
-   endforeach ()
+   file (GLOB_RECURSE doc_rsts RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} CONFIGURE_DEPENDS *.rst)
+   # Every .rst builds two corresponding .html files:
+   list (TRANSFORM doc_rsts
+         REPLACE "^(.+)\\.rst$" "html/\\1.html;html/\\1/index.html"
+         OUTPUT_VARIABLE doc_htmls)
 
    # Set PYTHONDONTWRITEBYTECODE to prevent .pyc clutter in the source directory
    add_custom_command (OUTPUT ${doc_htmls}
@@ -37,25 +36,22 @@ function (sphinx_build_html target_name doc_dir)
       ${CMAKE_COMMAND} -E env
          "PYTHONDONTWRITEBYTECODE=1"
       ${SPHINX_EXECUTABLE}
-         -qEnW -b html
+         -qnW -b dirhtml
+         -j "${NPROCS}"
          -c "${CMAKE_CURRENT_SOURCE_DIR}"
+         -d "${doctrees_dir}"
          "${CMAKE_CURRENT_SOURCE_DIR}"
          "${SPHINX_HTML_DIR}"
-      COMMAND
-      rm -rf "${SPHINX_HTML_DIR}/.doctrees" "${SPHINX_HTML_DIR}/.buildinfo"
       DEPENDS
       ${doc_rsts}
       COMMENT
       "Building HTML documentation with Sphinx"
    )
 
-   foreach (html IN LISTS doc_htmls)
-      install (FILES
-         ${CMAKE_CURRENT_BINARY_DIR}/${html}
-         DESTINATION
-         ${CMAKE_INSTALL_DOCDIR}/${doc_dir}/html
-      )
-   endforeach ()
+   # Install all HTML files
+   install (DIRECTORY "${SPHINX_HTML_DIR}/"
+            DESTINATION "${CMAKE_INSTALL_DOCDIR}/${doc_dir}/html"
+            FILES_MATCHING PATTERN "*.html")
 
    # Ensure additional Sphinx-generated content gets installed
    install (FILES
@@ -100,15 +96,17 @@ function (sphinx_build_man target_name)
    ProcessorCount (NPROCS)
 
    set (SPHINX_MAN_DIR "${CMAKE_CURRENT_BINARY_DIR}/man")
+   set (doctrees_dir "${SPHINX_MAN_DIR}.doctrees")
 
-   file (GLOB doc_rsts RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
+   file (GLOB_RECURSE doc_rsts RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} CONFIGURE_DEPENDS *.rst)
 
+   set (doc_mans)
    foreach (rst IN LISTS doc_rsts)
       # Only those with the :man_page: tag at the beginning build man pages
-      file (READ ${rst} rst_head LIMIT 256)
+      file (READ "${rst}" rst_head LIMIT 256)
       string (FIND "${rst_head}" ":man_page: " man_tag_pos)
-      # GREATER_EQUAL not in CMake until 3.7.
-      if (NOT man_tag_pos LESS "0")
+      if (man_tag_pos GREATER_EQUAL "0")
+         list (APPEND man_doc_rsts "${rst}")
          string (REGEX REPLACE
             "^.*:man_page: +([a-z0-9_]+).*$" "man\/\\1.3"
             man
@@ -124,12 +122,12 @@ function (sphinx_build_man target_name)
       ${CMAKE_COMMAND} -E env
          "PYTHONDONTWRITEBYTECODE=1"
       ${SPHINX_EXECUTABLE}
-         -qEW -b man
+         -qW -b man
+         -j "${NPROCS}"
          -c "${CMAKE_CURRENT_SOURCE_DIR}"
+         -d "${doctrees_dir}"
          "${CMAKE_CURRENT_SOURCE_DIR}"
          "${SPHINX_MAN_DIR}"
-      COMMAND
-      rm -rf "${SPHINX_MAN_DIR}/.doctrees" "${SPHINX_MAN_DIR}/.buildinfo"
       DEPENDS
       ${doc_rsts}
       COMMENT