CDRIVER-4767 support Sphinx 1.7.6 (#1492)

* import older `DirectoryHTMLBuilder` if needed

The import path of `DirectoryHTMLBuilder` was changed from `sphinx.builders.html` to `sphinx.builders.dirhtml` in Sphinx v2.0.0

* import `Directive`, not `SphinxDirective`

`SphinxDirective` was added in Sphinx v2.0.0

* do not import Project

`Project` was added in Sphinx v2.0.0

* update `needs_sphinx` to 1.7

* error if `add_css_file` is unavailable for HTML builder.

But do not error otherwise. This is intended to help build man pages without HTML requirements.

`Sphinx.add_css_file` was added in Sphinx v3.5.0

* use `builder-inited`

`config-inited` was added in Sphinx v1.8.0

* do not use `external` role

`external` role was added in intersphinx extension in v4.4

* do not use `noindexentry`

`noindexentry` option was added to C domain in Sphinx v3.2

* remove `name` from `index` directive

`name` option was added in Sphinx v3.0

* populate `man_pages` in `setup` instead of event handler

The `config-inited` event was added in Sphinx v1.8.0
The `ManualPageBuilder` constructor raises an exception for an empty `man_pages` value.

* remove parallel build of man pages

To avoid an error observed on Sphinx 1.7.6:
```
AttributeError: Can't pickle local object 'BuildEnvironment._read_parallel.<locals>.merge'
```

* remove unhelpful warning

An error is raised at runtime with a message suggesting to install `sphinx-design`. The warning was a source of confusion in CDRIVER-4767

* update NEWS for 1.25.3

* add upcoming NEWS for 1.25.4

Author: kevinAlbs

NEWS

@@ -1,9 +1,16 @@
+libmongoc 1.25.4 (Unreleased)
+=============================
+
+Fixes:
+
+  * Restore support for Sphinx 1.7.6 for man page build.
+
 libmongoc 1.25.3
 ================
 
 Fixes:
 
-  * Fix data race in `mongoc_cursor_get_host`.
+  * Disable shared libmongoc targets if `ENABLE_SHARED=OFF`
   * Fix documentation build with Python 3.9.
 
 Thanks to everyone who contributed to the development of this release.

build/cmake/SphinxBuild.cmake

@@ -144,7 +144,6 @@ function (sphinx_build_man target_name)
          "PYTHONDONTWRITEBYTECODE=1"
       ${SPHINX_EXECUTABLE}
          -qW -b man
-         -j "${NPROCS}"
          -c "${CMAKE_CURRENT_SOURCE_DIR}"
          -d "${doctrees_dir}"
          "${CMAKE_CURRENT_SOURCE_DIR}"

build/sphinx/mongoc_common.py

@@ -10,12 +10,15 @@
 
 from sphinx.application import Sphinx
 from sphinx.application import logger as sphinx_log
-from sphinx.builders.dirhtml import DirectoryHTMLBuilder
+try:
+    from sphinx.builders.dirhtml import DirectoryHTMLBuilder
+except ImportError:
+    # Try importing from older Sphinx version path.
+    from sphinx.builders.html import DirectoryHTMLBuilder
 from sphinx.config import Config
-from sphinx.project import Project
-from sphinx.util.docutils import SphinxDirective
+from docutils.parsers.rst import Directive
 
-needs_sphinx = "5.0"
+needs_sphinx = "1.7" # Do not require newer sphinx. EPEL packages build man pages with Sphinx 1.7.6. Refer: CDRIVER-4767
 author = "MongoDB, Inc"
 
 # -- Options for HTML output ----------------------------------------------
@@ -37,12 +40,9 @@ def _file_man_page_name(fpath: Path) -> str | None:
             continue
         return mat[1]
 
-
-def _collect_man(app: Sphinx, config: Config) -> None:
-    "Populate the man_pages value from the given source directory input"
+def _collect_man (app: Sphinx):
     # Note: 'app' is partially-formed, as this is called from the Sphinx.__init__
     docdir = Path(app.srcdir)
-    proj = Project(app.srcdir, config.source_suffix)
     # Find everything:
     children = docdir.rglob("*")
     # Find only regular files:
@@ -55,14 +55,17 @@ def _collect_man(app: Sphinx, config: Config) -> None:
     pairs: Iterable[tuple[Path, str]] = ((f, m) for f, m in with_man_name if m)
     # Populate the man_pages:
     for filepath, man_name in pairs:
-        docname = proj.path2doc(str(filepath))
+        # Generate the docname.
+        relative_path = filepath.relative_to(app.srcdir)
+        # The docname is relative to the source directory, and excludes the suffix.
+        docname = str(relative_path.parent / filepath.stem)
+
         assert docname, filepath
         man_pages.append((docname, man_name, "", [author], 3))
 
-
 # -- Options for manual page output ---------------------------------------
 
-# NOTE: This starts empty, but we populate it during "config-inited" in _collect_man() (see above)
+# NOTE: This starts empty, but we populate it in `setup` in _collect_man() (see above)
 man_pages: list[tuple[str, str, str, list[str], int]] = []
 
 # If true, show URL addresses after external links.
@@ -99,7 +102,7 @@ def add_ga_javascript(app: Sphinx, pagename: str, templatename: str, context: di
     )
 
 
-class VersionList(SphinxDirective):
+class VersionList(Directive):
     """Custom directive to generate the version list from an environment variable"""
 
     option_spec = {}
@@ -164,9 +167,8 @@ def generate_html_redirs(app: Sphinx, page: str, templatename: str, context: dic
     builder.css_files[:] = prev_css
     sphinx_log.debug("Wrote redirect: %r -> %r", path, page)
 
-
 def mongoc_common_setup(app: Sphinx):
-    app.connect("config-inited", _collect_man)
+    _collect_man(app)
     app.connect("html-page-context", generate_html_redirs)
     app.connect("html-page-context", add_ga_javascript)
     # Run sphinx-build -D analytics=1 to enable Google Analytics.

src/libbson/NEWS

@@ -1,3 +1,11 @@
+libbson 1.25.4 (Unreleased)
+===========================
+
+Fixes:
+
+  * Restore support for Sphinx 1.7.6 for man page build.
+
+
 libbson 1.25.3
 ==============
 

src/libmongoc/doc/conf.py

@@ -6,7 +6,12 @@
 from pathlib import Path
 from typing import Any
 
-from sphinx.builders.dirhtml import DirectoryHTMLBuilder
+try:
+    from sphinx.builders.dirhtml import DirectoryHTMLBuilder
+except ImportError:
+    # Try importing from older Sphinx version path.
+    from sphinx.builders.html import DirectoryHTMLBuilder
+
 from docutils.parsers.rst import directives, Directive
 from sphinx.application import Sphinx
 from sphinx.application import logger as sphinx_log
@@ -20,7 +25,7 @@
     from sphinx_design.dropdown import DropdownDirective
     has_sphinx_design = True
 except ImportError:
-    print ("Unable to import sphinx_design. Documentation cannot be built as HTML.")
+    pass
 
 # Ensure we can import "mongoc" extension module.
 this_path = os.path.dirname(__file__)
@@ -77,7 +82,7 @@
 _UPDATE_KEY = "update_external_inventories"
 
 
-def _maybe_update_inventories(app: Sphinx, config: Config):
+def _maybe_update_inventories(app: Sphinx):
     """
     We save Sphinx inventories for external projects saved within our own project
     so that we can support fully-offline builds. This is a convenience function
@@ -87,6 +92,7 @@ def _maybe_update_inventories(app: Sphinx, config: Config):
     value is defined.
     """
     prefix = "[libmongoc/doc/conf.py]"
+    config = app.config
     if not config[_UPDATE_KEY]:
         sphinx_log.info(
             "%s Using existing intersphinx inventories. Refresh by running with ‘-D %s=1’",
@@ -168,16 +174,16 @@ def _maybe_update_inventories(app: Sphinx, config: Config):
    Offer these substitutions for simpler variable references:
 
 .. |cmvar:CMAKE_BUILD_TYPE| replace::
-    :external+cmake:cmake:variable:`CMAKE_BUILD_TYPE <variable:CMAKE_BUILD_TYPE>`
+    :cmake:variable:`CMAKE_BUILD_TYPE <variable:CMAKE_BUILD_TYPE>`
 
 .. |cmvar:CMAKE_INSTALL_PREFIX| replace::
-    :external+cmake:cmake:variable:`CMAKE_INSTALL_PREFIX <variable:CMAKE_INSTALL_PREFIX>`
+    :cmake:variable:`CMAKE_INSTALL_PREFIX <variable:CMAKE_INSTALL_PREFIX>`
 
 .. |cmvar:CMAKE_PREFIX_PATH| replace::
-    :external+cmake:cmake:variable:`CMAKE_PREFIX_PATH <variable:CMAKE_PREFIX_PATH>`
+    :cmake:variable:`CMAKE_PREFIX_PATH <variable:CMAKE_PREFIX_PATH>`
 
 .. |cmcmd:find_package| replace::
-    :external+cmake:cmake:command:`find_package() <command:find_package>`
+    :cmake:command:`find_package() <command:find_package>`
 
 """
 
@@ -206,9 +212,14 @@ class EmptyDirective(Directive):
         def run(self):
             return []
 
+has_add_css_file = True
+        
 def check_html_builder_requirements (app):
-    if isinstance(app.builder, DirectoryHTMLBuilder) and not has_sphinx_design:
-        raise RuntimeError("The sphinx-design package is required to build HTML documentation but was not detected. Install sphinx-design.")
+    if isinstance(app.builder, DirectoryHTMLBuilder):
+        if not has_sphinx_design:
+            raise RuntimeError("The sphinx-design package is required to build HTML documentation but was not detected. Install sphinx-design.")
+        if not has_add_css_file:
+            raise RuntimeError("A newer version of Sphinx is required to build HTML documentation with CSS files. Upgrade Sphinx to v3.5.0 or newer")
 
 def setup(app: Sphinx):
     mongoc_common_setup(app)
@@ -219,6 +230,11 @@ def setup(app: Sphinx):
         app.add_directive("ad-dropdown", EmptyDirective)
         app.add_directive("tab-set", EmptyDirective)
     app.connect("html-page-context", add_canonical_link)
-    app.add_css_file("styles.css")
-    app.connect("config-inited", _maybe_update_inventories)
+    if hasattr(app, "add_css_file"):
+        app.add_css_file("styles.css")
+    else:
+        global has_add_css_file
+        has_add_css_file = False
+        
+    app.connect("builder-inited", _maybe_update_inventories)
     app.add_config_value(_UPDATE_KEY, default=False, rebuild=True, types=[bool])

src/libmongoc/doc/learn/get/docs.rst

@@ -36,7 +36,7 @@ to be run when the `pyproject.toml` file is changed.
 Running Sphinx
 **************
 
-Poetry can be used to execute the :external:doc:`man/sphinx-build` command::
+Poetry can be used to execute the :std:doc:`man/sphinx-build` command::
 
   $ poetry run sphinx-build -b dirhtml "./src/libmongoc/doc" "./_build/docs/html"
 
@@ -47,16 +47,16 @@ subdirectory.
 
   Because Sphinx builds many pages, the build may run quite slowly. For faster
   builds, it is recommended to use the
-  :external:option:`--jobs <sphinx-build.--jobs>` command-line option when
-  invoking :external:doc:`man/sphinx-build`.
+  :std:option:`--jobs <sphinx:sphinx-build.--jobs>` command-line option when
+  invoking :std:doc:`sphinx:man/sphinx-build`.
 
 
 Viewing the Documentation
 *************************
 
 To quickly view the rendered HTML pages, a simple local HTTP server can be
 spawned on the command line by using Python's built-in
-:external:mod:`http.server` module:
+:py:mod:`http.server` module:
 
 .. code-block:: sh
 

src/libmongoc/doc/learn/get/installing.rst

@@ -11,8 +11,8 @@ Installing Prebuilt MongoDB C Driver Libraries
 .. _Homebrew: https://brew.sh/
 
 The |libmongoc| and |libbson| libraries are often available in the package
-management repositories of `common Linux distributions <installing.linux_>`_ and
-`macOS via Homebrew <installing.macos_>`_.
+management repositories of :ref:`common Linux distributions <installing.linux>` and
+:ref:`macOS via Homebrew <installing.macos>`.
 
 .. note::
 
@@ -42,7 +42,8 @@ management repositories of `common Linux distributions <installing.linux_>`_ and
   package managers; Conan
   package managers; vcpkg
   pair: installation; package managers
-  :name: installing.pkgman
+
+.. _installing.pkgman:
 
 Cross Platform Installs Using Library Package Managers
 ******************************************************
@@ -135,7 +136,8 @@ CMake toolchain file at the initial configure command::
 
 .. index::
   ! pair: Linux; installation
-  :name: installing.linux
+
+.. _installing.linux:
 
 Installing in Linux
 *******************

src/libmongoc/doc/mongoc_client_encryption_opts_set_kms_credential_provider_callback.rst

@@ -34,7 +34,6 @@ Parameters
 .. rubric:: Related:
 
 .. c:type:: mongoc_kms_credentials_provider_callback_fn
-  :noindexentry:
 
   .. -
     The :noindexentry: prevents a one-off index entry for this item.