Speed up dev build of docs

Qiskit · Aug 14, 2023 · 01db047 · 01db047
1 parent c626be7
commit 01db047
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 6 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,7 +28,7 @@
 # The full version, including alpha/beta/rc tags
 release = "0.45.0"
 
-# For 'qiskit_sphinx_theme' tells it we're based at 'https://qiskit.org/<docs_url_prefix>'.
+# This tells 'qiskit_sphinx_theme' that we're based at 'https://qiskit.org/<docs_url_prefix>'.
 # Should not include the subdirectory for the stable version.
 docs_url_prefix = "documentation"
 
@@ -39,15 +39,15 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.mathjax",
-    "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.doctest",
-    "reno.sphinxext",
-    "sphinx_design",
+    "nbsphinx",
     "matplotlib.sphinxext.plot_directive",
     "qiskit_sphinx_theme",
-    "nbsphinx",
+    "reno.sphinxext",
+    "sphinx_design",
+    "sphinx_remove_toctrees",
 ]
 
 templates_path = ["_templates"]
@@ -116,6 +116,11 @@
 }  # enable segment analytics for qiskit.org/documentation
 html_static_path = ["_static"]
 
+# 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/*"]
+
 # ----------------------------------------------------------------------------------
 # Autodoc
 # ----------------------------------------------------------------------------------
@@ -209,6 +214,20 @@
 
 """
 
+# ---------------------------------------------------------------------------------------
+# Prod changes
+# ---------------------------------------------------------------------------------------
+
+if os.getenv("DOCS_PROD_BUILD"):
+    # `viewcode` slows down docs build by about 14 minutes.
+    extensions.append("sphinx.ext.viewcode")
+    # Include all pages in the left sidebar in prod.
+    remove_from_toctrees = []
+
+
+# ---------------------------------------------------------------------------------------
+# Custom extensions
+# ---------------------------------------------------------------------------------------
 
 def add_versions_to_config(_app, config):
     """Add a list of old documentation versions that should have links generated to them into the

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -34,6 +34,7 @@ ddt>=1.2.0,!=1.4.0,!=1.4.3
 Sphinx>=6.0
 qiskit-sphinx-theme~=1.14.0
 sphinx-design>=0.2.0
+sphinx-remove-toctrees
 nbsphinx~=0.9.2
 nbconvert~=7.7.1
 # TODO: switch to stable release when 4.1 is released

diff --git a/tox.ini b/tox.ini
@@ -73,7 +73,10 @@ setenv =
   {[testenv]setenv}
   QISKIT_SUPPRESS_PACKAGING_WARNINGS=Y
   RUST_DEBUG=1  # Faster to compile.
-passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS
+passenv =
+  {[testenv]passenv}
+  QISKIT_DOCS_BUILD_TUTORIALS
+  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