diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index ed8451a3c0..f445a2ec62 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,13 +1,15 @@
 # .readthedocs.yaml
 
+version: 2
+
 build:
-  image: latest
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
 
 python:
-  version: 3.8
-  pip_install: True
+  install:
+    - requirements: docs/readthedocs-requirements.txt
 
 # Don't build any extra formats
 formats: []
-
-requirements_file: docs/docs-requirements.txt
diff --git a/docs/conf.py b/docs/conf.py
index 494d2930fc..48a95e9929 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,7 +12,10 @@
 #
 import os
 import sys
+
+import better_apidoc
 import hyperpyyaml
+from sphinx.ext.autodoc.mock import mock
 
 sys.path.insert(-1, os.path.abspath("../"))
 
@@ -68,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"
@@ -93,24 +107,43 @@
 
 
 def run_apidoc(app):
-    """Generage 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__),
-        ]
-    )
+    """Generate API documentation"""
+
+    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
index b61ed36e2e..2db981926f 100644
--- a/docs/docs-requirements.txt
+++ b/docs/docs-requirements.txt
@@ -1,7 +1,6 @@
 better-apidoc>=0.3.1
 ctc-segmentation>=1.7.0
-fairseq
-kenlm
+https://github.com/kpu/kenlm/archive/master.zip
 numba>=0.54.1
 pyctcdecode
 recommonmark>=0.7.1
diff --git a/docs/readthedocs-requirements.txt b/docs/readthedocs-requirements.txt
new file mode 100644
index 0000000000..abe39961ad
--- /dev/null
+++ b/docs/readthedocs-requirements.txt
@@ -0,0 +1,7 @@
+# readthedocs only lets us define a single requirements file in the yaml
+# this file merges both the usual and the docs requirements so that everything
+# gets installed correctly.
+
+-r ../requirements.txt
+-r docs-requirements.txt
+torch==2.2.1