Speed up dev build of docs (Qiskit#10624)

* Speed up dev build of docs

* empty commit

* Fix tox issue

---------

Co-authored-by: Eric Arellano <arellano@Erics-MacBook-Pro.local>

Author: Eric-Arellano

.github/workflows/docs_deploy.yml

@@ -77,12 +77,14 @@ jobs:
           QISKIT_ENABLE_ANALYTICS: "true"
           # We've already built them.
           QISKIT_DOCS_BUILD_TUTORIALS: "never"
+          DOCS_PROD_BUILD: "true"
 
       - name: Build translatable strings
-        run: tox -e gettext
+        run: tox run -e gettext
         env:
           # We've already built them.
           QISKIT_DOCS_BUILD_TUTORIALS: "never"
+          DOCS_PROD_BUILD: "true"
 
       - name: Store built documentation artifact
         uses: actions/upload-artifact@v3

docs/conf.py

@@ -28,10 +28,9 @@
 # The full version, including alpha/beta/rc tags
 release = "0.45.0"
 
-# The language for content autogenerated by Sphinx or the default for gettext content translation.
 language = "en"
 
-# 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"
 
@@ -42,15 +41,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"]
@@ -132,6 +131,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
 # ----------------------------------------------------------------------------------
@@ -225,6 +229,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

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

tox.ini

@@ -73,7 +73,7 @@ setenv =
   {[testenv]setenv}
   QISKIT_SUPPRESS_PACKAGING_WARNINGS=Y
   RUST_DEBUG=1  # Faster to compile.
-passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS, QISKIT_CELL_TIMEOUT
+passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS, QISKIT_CELL_TIMEOUT, 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
@@ -103,7 +103,7 @@ commands =
 [testenv:gettext]
 base = docs
 deps =
-    {[testenv:docs]deps} 
+    {[testenv:docs]deps}
     sphinx-intl
 commands =
     sphinx-build -b gettext docs docs/_build/gettext {posargs}