CDRIVER-4788 do not require sphinx-design for man pages (#1483)

* do not require sphinx-design

sphinx-design is not used in the man pages. Do not require sphinx-design to enable building man pages when sphinx-design is not available.

* error if building HTML docs without sphinx-design

* remove `python3-sphinx` from mock install

`python3-sphinx` is listed in BuildRequires of spec file and does not need to be installed separately.

* update spec.patch to remove `python3-sphinx-design`

Intended to test the RPM build without the `python3-sphinx-design` dependency installed.

* commit staged files

This is intended to test files changed in a patch build.
Patch builds apply changes to index.

Author: kevinAlbs

.evergreen/etc/spec.patch

@@ -18,3 +18,13 @@
  Release:   1%{?dist}
  # See THIRD_PARTY_NOTICES
  License:   Apache-2.0 AND ISC AND MIT AND Zlib
+@@ -50,7 +50,8 @@ BuildRequires: perl-interpreter
+ # From man pages
+ BuildRequires: python3
+ BuildRequires: python3-sphinx
+-BuildRequires: python3-sphinx-design
++# python3-sphinx-design is intentionally removed to test that the build succeeds without python3-sphinx-design.
++# At present, python3-sphinx-design is not available in EPEL. Refer: CDRIVER-4767
+ 
+ Requires:   %{name}-libs%{?_isa} = %{version}-%{release}
+ # Sub package removed

.evergreen/scripts/build_snapshot_rpm.sh

@@ -76,7 +76,7 @@ build_dir=$(basename $(pwd))
 sudo mock -r ${config} --use-bootstrap-image --isolation=simple --clean
 sudo mock -r ${config} --use-bootstrap-image --isolation=simple --init
 mock_root=$(sudo mock -r ${config} --use-bootstrap-image --isolation=simple --print-root-path)
-sudo mock -r ${config} --use-bootstrap-image --isolation=simple --install rpmdevtools git rpm-build cmake python python3-sphinx gcc openssl-devel
+sudo mock -r ${config} --use-bootstrap-image --isolation=simple --install rpmdevtools git rpm-build cmake python gcc openssl-devel
 sudo mock -r ${config} --use-bootstrap-image --isolation=simple --copyin "$(pwd)" "$(pwd)/${spec_file}" /tmp
 sudo mock -r ${config} --use-bootstrap-image --isolation=simple --cwd "/tmp/${build_dir}" --chroot -- /bin/sh -c "(
   python build/calc_release_version.py | sed -E 's/([^-]+).*/\1/' > VERSION_CURRENT ;
@@ -110,6 +110,9 @@ tar_filename=$tar_filestem.tar
 tar_filepath="/tmp/$tar_filename"
 tgz_filepath="$HOME/rpmbuild/SOURCES/$expect_filename"
 echo "Creating source archive [$tgz_filepath]"
+# If Evergreen is running a patch build, changes have been git applied to the index.
+# Commit the changes to include them in the tarball.
+git commit -m "Include applied changes from a patch build" || true
 git archive --format=tar --output="$tar_filepath" --prefix="$tar_filestem/" HEAD
 mkdir -p "$tar_filestem"
 cp VERSION_CURRENT "$tar_filestem/."

src/libmongoc/doc/conf.py

@@ -6,11 +6,21 @@
 from pathlib import Path
 from typing import Any
 
-from docutils.parsers.rst import directives
+from sphinx.builders.dirhtml import DirectoryHTMLBuilder
+from docutils.parsers.rst import directives, Directive
 from sphinx.application import Sphinx
 from sphinx.application import logger as sphinx_log
 from sphinx.config import Config
-from sphinx_design.dropdown import DropdownDirective
+
+has_sphinx_design = False
+try:
+    # Try to import sphinx-design to include directives for HTML pages (e.g. tabs and dropdowns).
+    # sphinx-design is not required for building man pages.
+    # python-sphinx-design is not currently available on EPEL. The package for EPEL includes man pages.
+    from sphinx_design.dropdown import DropdownDirective
+    has_sphinx_design = True
+except ImportError:
+    print ("Unable to import sphinx_design. Documentation cannot be built as HTML.")
 
 # Ensure we can import "mongoc" extension module.
 this_path = os.path.dirname(__file__)
@@ -29,10 +39,12 @@
     # package building.
     # "sphinxcontrib.moderncmakedomain",
     "cmakerefdomain",
-    "sphinx_design",
     "sphinx.ext.mathjax",
 ]
 
+if has_sphinx_design:
+    extensions.append("sphinx_design")
+
 # General information about the project.
 project = "libmongoc"
 copyright = "2017-present, MongoDB, Inc"
@@ -176,22 +188,36 @@ def add_canonical_link(app: Sphinx, pagename: str, templatename: str, context: d
     context["metatags"] = context.get("metatags", "") + link
 
 
-class AdDropdown(DropdownDirective):
-    """A sphinx-design dropdown that can also be an admonition."""
-
-    option_spec = DropdownDirective.option_spec | {"admonition": directives.unchanged_required}
-
-    def run(self):
-        adm = self.options.get("admonition")
-        if adm is not None:
-            self.options.setdefault("class-container", []).extend(("admonition", adm))
-            self.options.setdefault("class-title", []).append(f"admonition-title")
-        return super().run()
-
+if has_sphinx_design:
+    class AdDropdown(DropdownDirective):
+        """A sphinx-design dropdown that can also be an admonition."""
+
+        option_spec = DropdownDirective.option_spec | {"admonition": directives.unchanged_required}
+
+        def run(self):
+            adm = self.options.get("admonition")
+            if adm is not None:
+                self.options.setdefault("class-container", []).extend(("admonition", adm))
+                self.options.setdefault("class-title", []).append(f"admonition-title")
+            return super().run()
+else:
+    class EmptyDirective(Directive):
+        has_content = True
+        def run(self):
+            return []
+        
+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.")
 
 def setup(app: Sphinx):
     mongoc_common_setup(app)
-    app.add_directive("ad-dropdown", AdDropdown)
+    app.connect("builder-inited", check_html_builder_requirements)
+    if has_sphinx_design:
+        app.add_directive("ad-dropdown", AdDropdown)
+    else:
+        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)