Mock some dependencies for docs

asumagic · pplantinga · commit cebd9942c3d2 · 2024-09-19T11:04:30.000-04:00
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,7 +13,9 @@
 import os
 import sys
 
+import better_apidoc
 import hyperpyyaml
+from sphinx.ext.autodoc.mock import mock
 
 sys.path.insert(-1, os.path.abspath("../"))
 
@@ -69,8 +71,19 @@
 
 autodoc_default_options = {}
 
-# Autodoc mock extra dependencies:
-autodoc_mock_imports = []
+# Autodoc mock extra dependencies -- doesn't work out of the box, because of better_apidoc.
+#
+# So, let's reuse the autodoc mock...
+#
+# We would also like to mock more imports than this but this is shockingly prone
+# to randomly breaking, so let's keep a small-ish set of dependencies that tend
+# to be more annoying to install and to nuke our CI on update
+autodoc_mock_imports = [
+    "k2",
+    "flair",
+    "fairseq",
+    "spacy",
+]
 
 # Order of API items:
 autodoc_member_order = "bysource"
@@ -95,23 +108,42 @@
 
 def run_apidoc(app):
     """Generate API documentation"""
-    import better_apidoc
-
-    better_apidoc.APP = app
-    better_apidoc.main(
-        [
-            "better-apidoc",
-            "-t",
-            "_apidoc_templates",
-            "--force",
-            "--no-toc",
-            "--separate",
-            "-o",
-            "API",
-            os.path.join("../", "speechbrain"),
-            os.path.dirname(hyperpyyaml.__file__),
-        ]
-    )
+
+    with mock(autodoc_mock_imports):
+        try:
+            better_apidoc.APP = app
+            better_apidoc.main(
+                [
+                    "better-apidoc",
+                    "-t",
+                    "_apidoc_templates",
+                    "--force",
+                    "--no-toc",
+                    "--separate",
+                    "-o",
+                    "API",
+                    os.path.join("../", "speechbrain"),
+                ]
+            )
+            better_apidoc.main(
+                [
+                    "better-apidoc",
+                    "-t",
+                    "_apidoc_templates",
+                    "--force",
+                    "--no-toc",
+                    "--separate",
+                    "-o",
+                    "API",
+                    os.path.dirname(hyperpyyaml.__file__),
+                ]
+            )
+        except Exception:
+            # because otherwise sphinx very helpfully eats the backtrace
+            import traceback
+
+            print(traceback.format_exc(), file=sys.stderr)
+            raise
 
 
 # -- Options for HTML output -------------------------------------------------
diff --git a/docs/docs-requirements.txt b/docs/docs-requirements.txt
@@ -1,14 +1,11 @@
 better-apidoc>=0.3.1
 ctc-segmentation>=1.7.0
-fairseq @ git+https://github.com/facebookresearch/fairseq.git@v0.12.3
-flair==0.13.1
 https://github.com/kpu/kenlm/archive/master.zip
 numba>=0.54.1
 pyctcdecode
 recommonmark>=0.7.1
 scikit-learn
 six
-spacy==3.7.4
 sphinx-rtd-theme>=0.4.3
 Sphinx>=3.4.3
 transformers
