CI for linting docs

.github/workflows/main.yml

@@ -72,6 +72,8 @@ jobs:
         run: python -m pip install -U tox
       - name: Run lint
         run: tox -elint
+      - name: Lint docs
+        run: tox -edocs-lint -- -W
   docs:
     name: docs
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -89,7 +89,7 @@ python when running. Additionally, the environment that tox sets up matches the
 environment more closely and it runs the tests in parallel (resulting in much faster
 execution). To run tests on all installed supported python versions and lint/style
 checks you can simply run `tox`. Or if you just want to run the tests once for a
-specific python version such as 3.10: `tox -epy310`.
+specific python version such as 3.10: `tox -e py310`.
 
 If you just want to run a subset of tests you can pass a selection regex to the test
 runner. For example, if you want to run all tests that have "dag" in the test id you can
@@ -138,13 +138,13 @@ The qiskit-experiments repository uses `black` for code formatting and style and
 `pylint` for linting. You can run these checks locally with
 
 ```
-tox -elint
+tox -e lint
 ```
 
 If there is a code formatting issue identified by black you can just run ``black``
-locally to fix this (or ``tox -eblack`` which will install it and run it).
+locally to fix this (or ``tox -e black`` which will install it and run it).
 
-Because `pylint` analysis can be slow, there is also a `tox -elint-incr` target, which
+Because `pylint` analysis can be slow, there is also a `tox -e lint-incr` target, which
 only applies `pylint` to files which have changed from the source github. On rare
 occasions this will miss some issues that would have been caught by checking the
 complete source tree, but makes up for this by being much faster (and those rare
@@ -341,8 +341,9 @@ https://github.com/Qiskit-Extensions/qiskit-experiments` and `git fetch upstream
 
 There are a few other build options available:
 
-* `tox -edocs-minimal`: build documentation without executing Jupyter code cells
-* `tox -edocs-parallel`: do a full build with multiprocessing (may crash on Macs)
+* `tox -e docs-minimal`: build documentation without executing Jupyter code cells
+* `tox -e docs-parallel`: do a full build with multiprocessing (may crash on Macs)
+* `tox -e docs-lint`: lint docs and check for broken links
 
 ### Deprecation policy
 

docs/conf.py

@@ -16,7 +16,6 @@
 
 import os
 import sys
-import subprocess
 import datetime
 
 # -- Path setup --------------------------------------------------------------

docs/lint/conf.py

@@ -0,0 +1,163 @@
+# This is the configuration file to run sphinx linting for `tox -edocs-nitpick`.
+# It will output warnings for each missing reference.
+
+import sys, os, datetime
+
+sys.path.insert(0, os.path.abspath("../"))
+sys.path.append(os.path.abspath("../_ext"))
+sys.path.append(os.path.abspath("../../"))
+
+# 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"
+
+# -- Project information -----------------------------------------------------
+# The short X.Y version
+version = "0.5"
+# The full version, including alpha/beta/rc tags
+release = "0.5.0"
+project = f"Qiskit Experiments {version}"
+copyright = f"2021-{datetime.date.today().year}, Qiskit Development Team"  # pylint: disable=redefined-builtin
+author = "Qiskit Development Team"
+
+
+project = "Qiskit Experiments"
+nitpicky = True
+
+# within nit-picking build, do not refer to any intersphinx object
+intersphinx_mapping = {}
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.extlinks",
+    "jupyter_sphinx",
+    "reno.sphinxext",
+    "sphinx_design",
+    "sphinx.ext.intersphinx",
+    "nbsphinx",
+    "autoref",
+    "autodoc_experiment",
+    "autodoc_analysis",
+    "autodoc_visualization",
+    "jupyter_execute_custom",
+]
+
+# Minimal options to let the build run successfully
+nbsphinx_timeout = 360
+nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never")
+nbsphinx_widgets_path = ""
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+napoleon_custom_sections = [("data keys", "params_style"), ("style parameters", "params_style")]
+autosummary_generate = True
+autodoc_default_options = {"inherited-members": None}
+numfig = True
+numfig_format = {"table": "Table %s"}
+language = "en"
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+pygments_style = "colorful"
+add_module_names = False
+modindex_common_prefix = ["qiskit_experiments."]
+html_theme = "qiskit_sphinx_theme"  # use the theme in subdir 'theme'
+html_context = {
+    "analytics_enabled": True,
+    "expandable_sidebar": True,
+}
+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),
+    "qiskit": ("https://qiskit.org/documentation/", None),
+    "uncertainties": ("https://pythonhosted.org/uncertainties", None),
+}
+if os.getenv("EXPERIMENTS_DEV_DOCS", None):
+    rst_prolog = """
+.. note::
+    This is the documentation for the current state of the development branch
+    of Qiskit Experiments. The documentation or APIs here can change prior to being
+    released.
+"""
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", maybe_skip_member)
+
+
+# Hardcoded list of class variables to skip in autodoc to avoid warnings
+# Should come up with better way to address this
+
+from qiskit_experiments.curve_analysis import ParameterRepr
+from qiskit_experiments.curve_analysis import SeriesDef
+
+
+def maybe_skip_member(app, what, name, obj, skip, options):
+    skip_names = [
+        "analysis",
+        "set_run_options",
+        "data_allocation",
+        "labels",
+        "shots",
+        "x",
+        "y",
+        "y_err",
+        "name",
+        "filter_kwargs",
+        "fit_func",
+        "signature",
+    ]
+    skip_members = [
+        ParameterRepr.repr,
+        ParameterRepr.unit,
+        SeriesDef.plot_color,
+        SeriesDef.plot_symbol,
+        SeriesDef.model_description,
+        SeriesDef.canvas,
+    ]
+    if not skip:
+        return (name in skip_names or obj in skip_members) and what == "attribute"
+    return skip
+
+
+###
+
+linkcheck_ignore = [
+    r"manuals/index.html",
+    "tutorials/index.html",
+    "howtos/index.html",
+    "cloud_service.html",
+    "apidocs/index.html",
+]
+
+# Ignore these objects
+nitpick_ignore_regex = [
+    ("py:.*", "qiskit.*"),
+    ("py:.*", "numpy.*"),
+    ("py:.*", "sklearn.*"),
+    ("py:.*", "scipy.*"),
+    ("py:.*", "datetime.*"),
+    ("py:.*", "IBM.*"),
+    ("py:.*", ".*\._.*"),
+    ("py:.*", "_.*"),
+    ("py:.*", "lmfit.*"),
+    ("py:.*", "uncertainties.*"),
+    ("py:.*", ".*__.*"),
+    ("py:.*", "typing.*"),
+    ("py:.*", ".*Error"),
+    ("py:.*", "Ellipsis"),
+    ("py:.*", "matplotlib.*"),
+]
+
+# Deprecated objects that should be ignored in the release notes
+nitpick_ignore_regex += [
+    ("py:*", "MplCurveDrawer.*"),
+    ("py:.*", "CliffordUtils.*"),
+]

docs/manuals/measurement/readout_mitigation.rst

@@ -180,4 +180,4 @@ See also
 
 * API documentation: :mod:`~qiskit_experiments.library.characterization.LocalReadoutError`, 
   :mod:`~qiskit_experiments.library.characterization.CorrelatedReadoutError`
-* Qiskit Textbook: `Measurement Error Mitigation <https://qiskit.org/textbook/ch-quantum-hardware/measurement-error-mitigation.html>`__
+* Qiskit Textbook: `Measurement Error Mitigation <https://learn.qiskit.org/course/quantum-hardware/measurement-error-mitigation>`__

docs/manuals/verification/quantum_volume.rst

@@ -190,5 +190,5 @@ See also
 --------
 
 * API documentation: :mod:`~qiskit_experiments.library.quantum_volume`
-* Qiskit Textbook: `Measuring Quantum Volume <https://qiskit.org/textbook/ch-quantum-hardware/measuring-quantum-volume.html>`__
+* Qiskit Textbook: `Measuring Quantum Volume <https://learn.qiskit.org/course/quantum-hardware/measuring-quantum-volume>`__
 

docs/tutorials/calibrations.rst

@@ -491,7 +491,7 @@ See also
 --------
 
 * API documentation: :mod:`~qiskit_experiments.calibration_management` and :mod:`~qiskit_experiments.library.calibration`
-* Qiskit Textbook: `Calibrating Qubits with Qiskit Pulse <https://qiskit.org/textbook/ch-quantum-hardware/calibrating-qubits-pulse.html>`__
+* Qiskit Textbook: `Calibrating Qubits with Qiskit Pulse <https://learn.qiskit.org/course/quantum-hardware-pulses/calibrating-qubits-using-qiskit-pulse>`__
 
 
 

qiskit_experiments/framework/matplotlib.py

@@ -19,7 +19,7 @@
 default_figure_canvas = FigureCanvasSVG  # pylint: disable=invalid-name
 """Matplotlib canvas to use when rendering a figure. This needs to be a
 canvas for a `non-interactive backend
-<https://matplotlib.org/stable/tutorials/introductory/usage.html#the-builtin-backends>`_.
+https://matplotlib.org/stable/users/explain/backends.html#the-builtin-backends>`_.
 The default is `FigureCanvasSVG`."""
 
 

qiskit_experiments/library/characterization/cr_hamiltonian.py

@@ -124,7 +124,7 @@ class CrossResonanceHamiltonian(BaseExperiment):
 
     # section: manual
         .. ref_website:: Qiskit Textbook 6.7,
-            https://qiskit.org/textbook/ch-quantum-hardware/hamiltonian-tomography.html
+            https://learn.qiskit.org/course/quantum-hardware-pulses/hamiltonian-tomography
     """
 
     # Number of CR pulses. The flat top duration per pulse is divided by this number.

qiskit_experiments/library/characterization/multi_state_discrimination.py

@@ -56,7 +56,7 @@ class MultiStateDiscrimination(BaseExperiment):
 
     # section: reference
         `Qiskit Textbook\
-        <https://qiskit.org/textbook/ch-quantum-hardware/accessing_higher_energy_states.html>`_
+        <https://learn.qiskit.org/course/quantum-hardware-pulses/accessing-higher-energy-states-with-qiskit-pulse>`_
 
     """
 

qiskit_experiments/library/characterization/rabi.py

@@ -51,8 +51,8 @@ class Rabi(BaseExperiment, RestlessMixin):
     # section: manual
         :ref:`Rabi Calibration`
 
-        See also `Qiskit Textbook <https://qiskit.org/textbook/ch-quantum-hardware/\
-        calibrating-qubits-pulse.html>`_
+        See also `Qiskit Textbook
+        <https://learn.qiskit.org/course/quantum-hardware-pulses/calibrating-qubits-using-qiskit-pulse>`_
         for the pulse level programming of a Rabi experiment.
 
     # section: analysis_ref

qiskit_experiments/library/quantum_volume/qv_experiment.py

@@ -42,7 +42,7 @@ class QuantumVolume(BaseExperiment):
         The Quantum Volume is determined by the largest circuit depth :math:`d_{max}`,
         and equals to :math:`2^{d_{max}}`.
         See `Qiskit Textbook
-        <https://qiskit.org/textbook/ch-quantum-hardware/measuring-quantum-volume.html>`_
+        <https://learn.qiskit.org/course/quantum-hardware/measuring-quantum-volume>`_
         for an explanation on the QV protocol.
 
         In the QV experiment we generate :class:`~qiskit.circuit.library.QuantumVolume` circuits on

qiskit_experiments/library/randomized_benchmarking/standard_rb.py

@@ -61,7 +61,7 @@ class StandardRB(BaseExperiment, RestlessMixin):
     Randomized Benchmarking (RB) is an efficient and robust method
     for estimating the average error rate of a set of quantum gate operations.
     See `Qiskit Textbook
-    <https://qiskit.org/textbook/ch-quantum-hardware/randomized-benchmarking.html>`_
+    <https://learn.qiskit.org/course/quantum-hardware/randomized-benchmarking>`_
     for an explanation on the RB method.
 
     A standard RB experiment generates sequences of random Cliffords

releasenotes/notes/0.2/0_2_release-eef5e3ba256fc750.yaml

@@ -19,7 +19,7 @@ features:
     ``qiskit_experiments.framework.matplotlib.default_figure_canvas`` to the
     desired canvas. Note that it has to be a canvas for one of the
     `non-interactive backend
-    <https://matplotlib.org/stable/tutorials/introductory/usage.html#the-builtin-backends>`_.
+    <https://matplotlib.org/stable/users/explain/backends.html#the-builtin-backends>`_.
     For example, you can set ``default_figure_canvas`` to
     :class:`~matplotlib.backends.backend_agg.FigureCanvasAgg` to use the
     ``AGG`` backend.

requirements-dev.txt

@@ -20,6 +20,7 @@ pylatexenc
 multimethod
 scikit-learn
 sphinx-copybutton
+sphinxcontrib-jupyter
 # Pin versions below because of build errors
 ipykernel<=6.21.3
 jupyter-client<=8.0.3

tox.ini

@@ -75,6 +75,17 @@ setenv =
 commands =
   sphinx-build -T -W --keep-going -b html {posargs} docs/ docs/_build/html
 
+[testenv:docs-lint]
+passenv = EXPERIMENTS_DEV_DOCS
+setenv = 
+  QISKIT_DOCS_SKIP_EXECUTE = 1
+commands =
+  sphinx-build -c docs/lint -T --keep-going -b linkcheck {posargs} docs/ docs/_build/html
+
+[pycodestyle]
+max-line-length = 100
+
+
 [testenv:docs-clean]
 skip_install = true
 deps =