Use new Furo theme (#1225)

### Summary This PR switches the docs to the new Furo ecosystem theme. ![image](https://github.com/Qiskit-Extensions/qiskit-experiments/assets/3870315/e93ee925-805e-466a-991a-fd30b663a24f) ### Details and comments New build variables have been added: - `FULL_TOCTREE` builds the full API toctree when turned on. By default, this is off for a fast build time and small file sizes. This is turned on for deployments. See Qiskit/qiskit_sphinx_theme#328 for more info. - `VERSION_STRING` and `RELEASE_STRING` are exposed so that the site can display an alternative version/release for builds. This is relevant for the dev site, where we would like to see the `git describe` commit string instead of the version to be clearer to users. The new theme currently does not expose the version/release (except for the release in the page title) since it doesn't have breadcrumbs, but this will be added after Qiskit/qiskit_sphinx_theme#361. ### Current known issues: The experiment gallery doesn't render correctly: ![image](https://github.com/Qiskit-Extensions/qiskit-experiments/assets/3870315/13bd6dfc-8732-4337-9e9b-67ce709f7409)
qiskit-community · Jul 19, 2023 · d9a767b · d9a767b
1 parent 5875483
commit d9a767b
Show file tree

Hide file tree

Showing 7 changed files with 72 additions and 39 deletions.
diff --git a/docs/_static/nbsphinx-gallery.css b/docs/_static/nbsphinx-gallery.css
@@ -0,0 +1,31 @@
+.nbsphinx-gallery {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+    gap: 5px;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.nbsphinx-gallery>a {
+    padding: 5px;
+    border: 1px dotted currentColor;
+    border-radius: 2px;
+    text-align: center;
+}
+
+.nbsphinx-gallery>a:hover {
+    border-style: solid;
+}
+
+.nbsphinx-gallery img {
+    max-width: 100%;
+    max-height: 100%;
+}
+
+.nbsphinx-gallery>a>div:first-child {
+    display: flex;
+    align-items: start;
+    justify-content: center;
+    height: 120px;
+    margin-bottom: 5px;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,7 +16,6 @@
 
 import os
 import sys
-import subprocess
 import datetime
 
 # -- Path setup --------------------------------------------------------------
@@ -36,9 +35,11 @@
 
 # -- Project information -----------------------------------------------------
 # The short X.Y version
-version = "0.6"
+version = os.getenv("VERSION_STRING", "0.6")
+
 # The full version, including alpha/beta/rc tags
-release = "0.6.0"
+release = os.getenv("RELEASE_STRING", "0.6.0")
+
 project = "Qiskit Experiments"
 copyright = f"2021-{datetime.date.today().year}, Qiskit Development Team"  # pylint: disable=redefined-builtin
 author = "Qiskit Development Team"
@@ -65,10 +66,21 @@
     "autodoc_analysis",
     "autodoc_visualization",
     "jupyter_execute_custom",
+    "sphinx_remove_toctrees",
 ]
 
+# Remove stubs from the toctree by default because the full build is slow
+# This is turned off for docs deployment
+if not os.getenv("FULL_TOCTREE", None):
+    remove_from_toctrees = ["stubs/*"]
+
 html_static_path = ["_static"]
 templates_path = ["_templates"]
+# Manually add the gallery CSS file for now
+# TODO: Figure out why the styling is not working by default
+html_css_files = [
+    "nbsphinx-gallery.css",
+]
 
 nbsphinx_timeout = 360
 nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never")
@@ -137,34 +149,21 @@
 # package. Works only for the HTML builder currently.
 modindex_common_prefix = ["qiskit_experiments."]
 
-# -- Configuration for extlinks extension ------------------------------------
-# Refer to https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
-
-
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "qiskit_sphinx_theme"  # use the theme in subdir 'theme'
+html_theme = "qiskit-ecosystem"
 
 html_context = {
     "analytics_enabled": True,
     "expandable_sidebar": True,
 }
 
+html_title = f"{project} {release}"
+
 docs_url_prefix = "ecosystem/experiments"
 
 html_last_updated_fmt = "%Y/%m/%d"
 
-html_theme_options = {
-    "logo_only": True,
-    "display_version": True,
-    "prev_next_buttons_location": "bottom",
-    "style_external_links": True,
-}
-
-
 autoclass_content = "both"
 intersphinx_mapping = {
     "matplotlib": ("https://matplotlib.org/stable/", None),

diff --git a/docs/index.rst b/docs/index.rst
@@ -92,22 +92,12 @@ We've divided up the documentation into four sections with different purposes:
 
             To the API reference
 
-.. toctree::
-    :hidden:
-    :caption: Tutorials
-
-    All Tutorials <tutorials/index>
-    tutorials/intro
-    tutorials/getting_started
-    Calibrations <tutorials/calibrations>
-    Data Processor <tutorials/data_processor>
-    Curve Analysis <tutorials/curve_analysis>
-    Visualization <tutorials/visualization>
-    Custom Experiments <tutorials/custom_experiment>
-
 .. toctree::
     :hidden:
 
+    Qiskit Experiments Home <self>
+    Getting Started <tutorials/getting_started>
+    tutorials/index
     howtos/index
     manuals/index
     apidocs/index

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -5,7 +5,7 @@ astroid~=2.14.2  # Must be kept aligned to what pylint wants
 jinja2==3.0.3
 sphinx>=6.2.1,<=7
 jupyter-sphinx>=0.4.0
-qiskit-sphinx-theme~=1.12.0
+qiskit-sphinx-theme~=1.14.0rc1
 sphinx-design~=0.4.1
 pygments>=2.4
 reno>=4.0.0
@@ -24,4 +24,5 @@ coverage>=5.5
 # Pin versions below because of build errors
 ipykernel<=6.21.3
 jupyter-client<=8.0.3
-ipython<8.13.0 ; python_version<"3.9"  # for python 3.8 compatibility
+ipython<8.13.0 ; python_version<"3.9"  # for python 3.8 compatibility
+sphinx-remove-toctrees
diff --git a/tools/deploy_documentation.sh b/tools/deploy_documentation.sh
@@ -21,7 +21,7 @@ sudo apt-get install -y ./rclone.deb
 RCLONE_CONFIG_PATH=$(rclone config file | tail -1)
 
 # Build the documentation.
-tox -edocs
+EXPERIMENTS_DEV_DOCS=1 FULL_TOCTREE=1 tox -edocs
 
 echo "show current dir: "
 pwd

diff --git a/tools/deploy_documentation_dev.sh b/tools/deploy_documentation_dev.sh
@@ -21,7 +21,7 @@ sudo apt-get install -y ./rclone.deb
 RCLONE_CONFIG_PATH=$(rclone config file | tail -1)
 
 # Build the documentation.
-EXPERIMENTS_DEV_DOCS=1 tox -edocs
+EXPERIMENTS_DEV_DOCS=1 FULL_TOCTREE=1 RELEASE_STRING=`git describe` tox -edocs
 
 echo "show current dir: "
 pwd

diff --git a/tox.ini b/tox.ini
@@ -67,19 +67,31 @@ commands = black {posargs} qiskit_experiments test tools setup.py
 
 [testenv:docs]
 usedevelop = False
-passenv = EXPERIMENTS_DEV_DOCS
+passenv =
+  EXPERIMENTS_DEV_DOCS
+  FULL_TOCTREE
+  RELEASE_STRING
+  VERSION_STRING
 commands =
   sphinx-build -T -W --keep-going -b html {posargs} docs/ docs/_build/html
 
 [testenv:docs-parallel]
 usedevelop = False
-passenv = EXPERIMENTS_DEV_DOCS
+passenv =
+  EXPERIMENTS_DEV_DOCS
+  FULL_TOCTREE
+  RELEASE_STRING
+  VERSION_STRING
 commands =
   sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html
 
 [testenv:docs-minimal]
 usedevelop = False
-passenv = EXPERIMENTS_DEV_DOCS
+passenv =
+  EXPERIMENTS_DEV_DOCS
+  FULL_TOCTREE
+  RELEASE_STRING
+  VERSION_STRING
 setenv = 
   QISKIT_DOCS_SKIP_EXECUTE = 1
 commands =