Use sphinx-remove-toctree

Qiskit · Jul 26, 2023 · f9da86b · f9da86b
1 parent 2968e8b
commit f9da86b
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 3 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,12 +14,12 @@
 
 """Sphinx documentation builder."""
 
-# -- General configuration ---------------------------------------------------
 import datetime
 import doctest
+import os
 
 project = "Qiskit"
-copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"  # pylint: disable=redefined-builtin
+project_copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"
 author = "Qiskit Development Team"
 
 # The short X.Y version
@@ -37,8 +37,8 @@
     "sphinx.ext.doctest",
     "reno.sphinxext",
     "sphinx_design",
+    "sphinx_remove_toctrees",
     "matplotlib.sphinxext.plot_directive",
-    "sphinx.ext.doctest",
     "qiskit_sphinx_theme",
 ]
 
@@ -72,6 +72,11 @@
     "matplotlib": ("https://matplotlib.org/stable/", None),
 }
 
+# This speeds up the docs build because it works around the Furo theme's slowdown from the left
+# sidebar when the site has lots of HTML pages. But, it results in a much worse user experience,
+# so we only use it in dev/CI builds.
+remove_from_toctrees = ["stubs/*"]
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "qiskit"
@@ -127,3 +132,13 @@
 # >> code
 # output
 doctest_test_doctest_blocks = ""
+
+# ---------------------------------------------------------------------------------------
+# Prod changes
+# ---------------------------------------------------------------------------------------
+
+if os.getenv("DOCS_PROD_BUILD"):
+    # `viewcode` down the Furo-based theme by about 14 minutes.
+    extensions.append("sphinx.ext.viewcode")
+    # Include all pages in the left sidebar in prod.
+    remove_from_toctrees = []
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -20,6 +20,7 @@ seaborn>=0.9.0
 reno @ git+https://github.com/openstack/reno.git@81587f616f17904336cdc431e25c42b46cd75b8f
 Sphinx>=5.0
 qiskit-sphinx-theme~=1.14.0
+sphinx-remove-toctrees
 sphinx-design>=0.2.0
 pygments>=2.4
 scikit-learn>=0.20.0

diff --git a/tox.ini b/tox.ini
@@ -73,6 +73,8 @@ setenv =
   {[testenv]setenv}
   QISKIT_SUPPRESS_PACKAGING_WARNINGS=Y
   RUST_DEBUG=1  # Faster to compile.
+passenv =
+  DOCS_PROD_BUILD
 deps =
   setuptools_rust  # This is work around for the bug of tox 3 (see #8606 for more details.)
   -r{toxinidir}/requirements-dev.txt