Switch to using Tox (#1459)

<!--
⚠️ If you do not respect this template, your pull request will be
closed.
⚠️ Your pull request title should be short detailed and understandable
for all.
⚠️ If your pull request fixes an open issue, please link to the issue.

✅ I have added the tests to cover my changes.
✅ I have updated the documentation accordingly.
✅ I have read the CONTRIBUTING document.
-->

### Summary

Previously, there was no standardized way to build the docs locally.
While Tox isn't perfect, it aligns us with the rest of the Qiskit
ecosystem.

Switching to Tox is important here because it de-duplicates our
requirements, which were specified both in requirements-dev.txt and
again in azure-pipelines.yaml.

### Details and comments

This also fixes two Sphinx warnings due to bad config in `conf.py`.

I couldn't actually get NBSphinx to work on my mac due to import errors.
But this is still some forward progress, so I put up the PR. CI at least
will now use tox, and continue to produce a zip of the docs that CI
users can inspect.

.gitignore

@@ -20,4 +20,5 @@ __pycache__/
 
 .stestr/
 
-_build/
+_build/
+.tox/

README.md

@@ -54,37 +54,21 @@ Because the tutorials are executed as part of the build process, and eventually
 
 To add a gallery image to a notebook, select a cell with an output image and add `nbsphinx-thumbnail` as a cell tag.  To see the cell tags go to: `View -> Cell Toolbar -> Tags` in the notebook menu.  Adding gallery images from images not generated inside of the notebooks themselves should be avoided if possible as this gets messy in the present build system.
 
-
 ## Building documentation
 
-In addition to serving up standalone notebooks, this repository also includes the infrastructure needed to build the tutorials into HTML documentation using [Sphinx](https://www.sphinx-doc.org/).  Along with the Qiskit dependencies, building the documentation requires the following:
-
-1. Fork and clone the forked repository. 
-2. Create a new virtual environment and install pip:
-```bash
-conda create -n qiskit-tutorials-dev pip
-```
-3. Activate virtual environment:
-```bash
-conda activate qiskit-tutorials-dev
-```
-4. Install python dependencies in your new virtual environment:
-```bash
-pip install -r requirements-dev.txt
-```
-5. Install non-python dependencies:
-```bash
-conda install pandoc graphviz
-```
-6. Create a local build:
-```bash
-sphinx-build -b html . _build
-```
+In addition to serving up standalone notebooks, this repository also includes the infrastructure needed to build the tutorials into HTML documentation using [Sphinx](https://www.sphinx-doc.org/).
+
+We use [Tox](https://tox.wiki/en/latest/), which you will need to install globally (e.g. using [`pipx`](https://pypa.github.io/pipx/)).
+
+1. Fork and clone the forked repository.
+2. `tox -e docs`
+
+Sometimes Sphinx's caching can get in a bad state. First, try running `tox -e docs-clean`, which will remove Sphinx's cache. If you are still having issues, try running `tox -e docs -r`. `-r` tells Tox to reinstall the dependencies.
 
 ## Authors and Citation
 
 Qiskit Tutorials is the work of [many people](https://github.com/Qiskit/qiskit-tutorials/graphs/contributors) who contribute to the project at different levels. If you use Qiskit, please cite as per the included [BibTeX
-file](https://github.com/Qiskit/qiskit/blob/master/Qiskit.bib).
+file](https://github.com/Qiskit/qiskit-terra/blob/main/CITATION.bib).
 
 ## License
 

azure-pipelines.yml

@@ -13,8 +13,8 @@ pool:
   vmImage: 'ubuntu-latest'
 strategy:
   matrix:
-    Python38:
-      python.version: '3.7'
+    Python39:
+      python.version: '3.9'
 variables:
   PIP_CACHE_DIR: $(Pipeline.Workspace)/.pip
 steps:
@@ -33,19 +33,10 @@ steps:
   displayName: Cache pip
 - bash: |
     set -e
-    python -m pip install --upgrade pip setuptools wheel virtualenv
-    virtualenv /tmp/docs_build
-    source /tmp/docs_build/bin/activate
-    pip install -c constraints.txt -U qiskit jupyter sphinx nbsphinx qiskit_sphinx_theme networkx scikit-learn
-    pip install -c constraints.txt 'matplotlib<3.3'
-    pip install -c constraints.txt -U qiskit[visualization] cvxpy
-    pip install -c constraints.txt pyscf
     sudo apt-get install -y pandoc graphviz
-  displayName: 'Install dependencies'
-- bash: |
-    set -e
-    source /tmp/docs_build/bin/activate
-    sphinx-build -b html . _build/html
+    python -m pip install -U tox
+  displayName: 'Install system dependencies and tox'
+- bash: tox -e docs
   displayName: 'Build Docs'
 - task: ArchiveFiles@2
   inputs:

conf.py

@@ -1,8 +1,6 @@
-# -*- coding: utf-8 -*-
-
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2018, 2020.
+# (C) Copyright IBM 2018, 2023.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -12,34 +10,12 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-# pylint: disable=invalid-name
 # Configuration file for the Sphinx documentation builder.
 #
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-"""
-Sphinx documentation builder
-"""
-
-import os
-import sys
-# Set env flag so that we can doc functions that may otherwise not be loaded
-# see for example interactive visualizations in qiskit.visualization.
-os.environ['QISKIT_DOCS'] = 'TRUE'
-if sys.platform == 'darwin':
-    os.environ['QISKIT_IN_PARALLEL'] = 'TRUE'
 
 # -- Project information -----------------------------------------------------
 project = 'Qiskit Tutorials'
@@ -53,13 +29,6 @@
 
 # -- General configuration ---------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     'sphinx.ext.mathjax',
     'sphinx.ext.extlinks',
@@ -68,21 +37,14 @@
 ]
 html_static_path = ['_static']
 
-html_sourcelink_suffix = ''
 exclude_patterns = ['*.ipynb', '_build', 'legacy_tutorials',
-                    '**.ipynb_checkpoints']
+                    '**.ipynb_checkpoints', '.tox']
 
-cell_timeout = int(os.getenv('QISKIT_CELL_TIMEOUT', 180))
-nbsphinx_timeout = cell_timeout
+nbsphinx_timeout = 300
 nbsphinx_execute = 'always'
-nbsphinx_execute_arguments = [
-    "--InlineBackend.figure_formats={'png', 'pdf'}",
-    "--InlineBackend.rc={'figure.dpi': 96}",
-]
-
-nbsphinx_thumbnails = {
-}
-
+nbsphinx_widgets_path = ""
+html_sourcelink_suffix = ""
+nbsphinx_thumbnails = {"**": "_static/no_image.png"}
 
 nbsphinx_prolog = """
 {% set docname = env.doc2path(env.docname, base=None) %}
@@ -112,12 +74,7 @@
 numfig_format = {
     'table': 'Table %s'
 }
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'colorful'
@@ -127,17 +84,9 @@
 # py:function directives.
 add_module_names = False
 
-
-# -- 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_sphinx_theme'
 
 html_logo = 'images/logo.png'
 html_last_updated_fmt = '%Y/%m/%d'
@@ -147,7 +96,6 @@
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': True,
-    'style_nav_header_background': '#212121',
 }
 
 autoclass_content = 'both'

tox.ini

@@ -0,0 +1,18 @@
+[tox]
+minversion = 3.15
+envlist = py310,py39,py38
+
+[testenv]
+no_package = true
+install_command = pip install -c{toxinidir}/constraints.txt -U {opts} {packages}
+deps =
+  -r{toxinidir}/requirements-dev.txt
+
+[testenv:docs]
+commands =
+  sphinx-build -j auto -b html {toxinidir} {toxinidir}/_build/html/
+
+[testenv:docs-clean]
+deps =
+allowlist_externals = rm
+commands = rm -rf {toxinidir}/_build/