From 01db0479c57397498e3367d28ec5e2e102178b61 Mon Sep 17 00:00:00 2001
From: Eric Arellano <arellano@Erics-MacBook-Pro.local>
Date: Mon, 14 Aug 2023 11:24:24 -0700
Subject: [PATCH] Speed up dev build of docs

---
 docs/conf.py         | 29 ++++++++++++++++++++++++-----
 requirements-dev.txt |  1 +
 tox.ini              |  5 ++++-
 3 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 851fd3aa424d..f64049d02022 100644
--- 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
index fe363cba1f44..9585b2d40ee2 100644
--- 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
index d62dcc9fa6cc..04cb72524ea7 100644
--- 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