Documentation fixes and formatting (#1095)

### Summary

This PR is essentially the documentation fixes from #1080 since the lint
CI pipeline needs more work.

### Details and comments

- The docs are no longer incompatible with the newest
sphinx-autodoc-typehints so the version pin from #1017 has been removed.
This closes #1018.
- Updates curve analysis tutorial to the newest version (#983 had
accidentally reverted to an older version)
- Changes arxiv autolinks from pdfs to abstract page to be more user
friendly
- Renames the new ExperimentData how-to to rerunning analysis and adds
additional info on using `add_data`
- Moved functions from `curve_analysis/data_processing.py` to `utils.py`
- Changes benchmarking experiments to verification experiments on the
manual page to match the library API page
- Added referenced classes and functions that weren't included in the
docs
- Various formatting fixes for passing Sphinx nitpick mode

Author: coruscating

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,6 @@
 ### Summary
 
-Please describe what this PR changes as concisely as possible. Link to the issue(s) 
-that this addresses, if any.
+Please describe what this PR changes as concisely as possible. Link to the issue(s) that this addresses, if any.
 
 ### Details and comments
 
@@ -12,15 +11,11 @@ Some details that should be in this section include:
 - What tests and documentation have been added/updated
 - What do users and developers need to know about this change
 
-Note that this entire PR description field will be used as the commit message upon
-merge, so please keep it updated along with the PR. Secondary discussions, such as
-intermediate testing and bug statuses that do not affect the final PR, should be in the
-PR comments.
+Note that this entire PR description field will be used as the commit message upon merge, so please keep it updated along with the PR. Secondary discussions, such as intermediate testing and bug statuses that do not affect the final PR, should be in the PR comments.
 
 ### PR checklist (delete when all criteria are met)
 
 - [ ] I have read the contributing guide `CONTRIBUTING.md`.
 - [ ] I have added the tests to cover my changes.
 - [ ] I have updated the documentation accordingly.
-- [ ] I have added a release note file using `reno` if this change needs to be 
-      documented in the release notes.
+- [ ] I have added a release note file using `reno` if this change needs to be documented in the release notes.

CONTRIBUTING.md

@@ -227,18 +227,18 @@ should look something like:
 ```yaml
 features:
   - |
-    Introduced a new feature foo, that adds support for doing something to
-    ``QuantumCircuit`` objects. It can be used by using the foo function,
+    Introduced a new feature foo that adds support for doing something to
+    :class:`~qiskit.circuit.QuantumCircuit` objects. It can be used by using the foo function,
     for example::
 
       from qiskit import foo
       from qiskit import QuantumCircuit
       foo(QuantumCircuit())
 
   - |
-    The ``qiskit.QuantumCircuit`` module has a new method ``foo()``. This is
-    the equivalent of calling the ``qiskit.foo()`` to do something to your
-    QuantumCircuit. This is the equivalent of running ``qiskit.foo()`` on
+    The :class:`~qiskit.circuit.QuantumCircuit` class has a new method :meth:`.foo`. This is
+    the equivalent of calling :func:`qiskit.foo` to do something to your
+    QuantumCircuit. This is the equivalent of running :func:`qiskit.foo` on
     your circuit, but provides the convenience of running it natively on
     an object. For example::
 
@@ -249,11 +249,11 @@ features:
 
 deprecations:
   - |
-    The ``qiskit.bar`` module has been deprecated and will be removed in a
-    future release. Its sole function, ``foobar()`` has been superseded by the
-    ``qiskit.foo()`` function which provides similar functionality but with
+    The :mod:`qiskit.bar` module has been deprecated and will be removed in a
+    future release. Its sole function, :func:`foobar` has been superseded by the
+    :func:`qiskit.foo` function which provides similar functionality but with
     more accurate results and better performance. You should update your calls
-    ``qiskit.bar.foobar()`` calls to ``qiskit.foo()``.
+    :func:`qiskit.bar.foobar` calls to :func:`qiskit.foo`.
 ```
 
 You can also look at existing release notes for more examples.
@@ -348,9 +348,12 @@ There are a few other build options available:
 Qiskit Experiments is part of Qiskit and, therefore, the [Qiskit Deprecation
 Policy](https://qiskit.org/documentation/contributing_to_qiskit.html#deprecation-policy)
 fully applies here. We have a deprecation decorator for showing deprecation warnings. To
-deprecate a function:
+deprecate a function, for example:
 
 ```python
+
+  from qiskit_experiments.warnings import deprecated_function
+
   @deprecated_function(last_version="0.3", msg="Use new_function instead.")
   def old_function(*args, **kwargs):
       pass
@@ -361,6 +364,8 @@ deprecate a function:
 To deprecate a class:
 
 ```python
+  from qiskit_experiments.warnings import deprecated_class
+
   @deprecated_class(last_version="0.3", new_cls=NewCls)
   class OldClass:
       pass
@@ -408,5 +413,5 @@ following steps:
 4.  Generate a PR on the meta-repository to bump the qiskit-experiments version and
     meta-package version.
 
-The `stable/*` branches should only receive changes in the form of bug fixes.
+The `stable/*` branches should only receive changes in the form of bug fixes. If you're making a bug fix PR that you believe should be backported to the current stable release, tag it with `backport stable potential`.
 

docs/GUIDELINES.md

@@ -6,6 +6,8 @@ Contents:
 - [Guidelines for writing documentation](#guidelines-for-writing-documentation)
   - [Introduction](#introduction)
     - [General formatting guidelines](#general-formatting-guidelines)
+    - [Writing code](#writing-code)
+    - [Referencing objects](#referencing-objects)
     - [Tutorials](#tutorials)
     - [How-to guides](#how-to-guides)
     - [Experiment manuals](#experiment-manuals)
@@ -23,6 +25,22 @@ Qiskit Experiments documentation is split into four sections:
 - Experiment manuals for information on specific experiments
 - API reference for technical documentation
 
+### General formatting guidelines 
+
+* For experiments, the documentation title should be just the name of the experiment. Use
+  regular capitalization
+* Use headers, subheaders, subsubheaders etc. for hierarchical text organization. No
+  need to number the headers
+* Use present progressive for subtitles, such as "Saving experiment data to the
+  database" instead of "Save experiment data to the database"
+* Use math notation as much as possible (e.g. use $\frac{\pi}{2}$ instead of pi-half or
+  pi/2)
+* Use device names as shown in the IBM Quantum Services dashboard, e.g. `ibmq_lima`
+  instead of IBMQ Lima
+* put identifier names (e.g. osc_freq) in code blocks using double backticks, i.e. `osc_freq`
+
+### Writing code
+
 All documentation is written in reStructuredText format and then built into formatted
 text by Sphinx. Code cells can be written using `jupyter-execute` blocks, which will be
 automatically executed, with both code and output shown to the user:
@@ -31,36 +49,29 @@ automatically executed, with both code and output shown to the user:
 
         # write Python code here
 
-Your code should use the appropriate mock backend to show what expected experiment
-results might look like for the user. To instantiate a mock backend without exposing it
-to the user, use the `:hide-code:` and `:hide-output:` directives:
-
-    .. jupyter-execute::
-        :hide-code:
-        :hide-output:
-
-        from qiskit.test.ibmq_mock import mock_get_backend
-        backend = mock_get_backend('FakeLima')
-
 To display a block without actually executing the code, use the `.. jupyter-input::` and
 `.. jupyter-output::` directives. To ignore an error from a Jupyter cell block, use the
 `:raises:` directive. To see more options, consult the [Jupyter Sphinx documentation](https://jupyter-sphinx.readthedocs.io/en/latest/).
 
-### General formatting guidelines 
+### Referencing objects
+
+Modules, classes, methods, functions, and attributes mentioned in the documentation
+should link to their API documentation whenever possible using the `:mod:`, `:class:`,
+`:meth:`, `:func:`, and `:attr:` directives followed by the name of the object in single
+backticks. Here are some common usage patterns:
+
+- `` :class:`.CurveAnalysis` ``: This will render a link to the curve analysis class
+  `CurveAnalysis` if its name is unique.
+- `` :class:`qiskit_experiments.curve_analysis.CurveAnalysis` ``: This will render the 
+  full path to the object with a link as long as the path is correct.
+- `` :class:`~qiskit_experiments.curve_analysis.CurveAnalysis` ``: This will render only
+  the object name itself instead of the full path. It's simpler to use the first pattern
+  instead if the name is unique.
+
+Consult the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) for more detailed syntax.
 
-* For experiments, documentation title should be just the name of the experiment. Use
-  regular capitalization. 
-* Use headers, subheaders, subsubheaders etc. for hierarchical text organization. No
-  need to number the headers
-* Use present progressive for subtitles, such as "Saving experiment data to the
-  database" instead of "Save experiment data to the database"
-* Use math notation as much as possible (e.g. use $\frac{\pi}{2}$ instead of pi-half or
-  pi/2)
-* Use device names as shown in the IBM Quantum Services dashboard, e.g. `ibmq_lima`
-  instead of IBMQ Lima
-* put identifier names (e.g. osc_freq) in code blocks using double backticks, i.e. `osc_freq`
 
-Below we provide templates and guidelines for each of these types of documentation.
+Below are templates and guidelines for each of these types of documentation.
 
 ### Tutorials
 

docs/_ext/autoref.py

@@ -30,6 +30,7 @@ class WebSite(Directive):
         .. ref_website:: qiskit-experiments, https://github.com/Qiskit/qiskit-experiments
 
     """
+
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
@@ -67,6 +68,7 @@ class Arxiv(Directive):
     If an article is not found, no journal information will be shown.
 
     """
+
     required_arguments = 2
     optional_arguments = 0
     final_argument_whitespace = False
@@ -95,7 +97,7 @@ def run(self):
         if journal:
             ret_node += nodes.Text(journal)
         ret_node += nodes.Text(" ")
-        ret_node += nodes.reference(text="(open)", refuri=paper.pdf_url)
+        ret_node += nodes.reference(text="(open)", refuri=paper.entry_id)
 
         return [ret_node]
 

docs/conf.py

@@ -10,13 +10,6 @@
 # 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
-
 """
 Sphinx documentation builder.
 """
@@ -53,13 +46,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.napoleon",
     "sphinx.ext.autodoc",
@@ -94,11 +80,11 @@
 # These should ideally be automatically generated using a custom macro to specify
 # chosen cells for thumbnails, like the nbsphinx-gallery tag
 nbsphinx_thumbnails = {
-    "manuals/benchmarking/quantum_volume": "_images/quantum_volume_2_0.png",
+    "manuals/verification/quantum_volume": "_images/quantum_volume_2_0.png",
     "manuals/measurement/readout_mitigation": "_images/readout_mitigation_4_0.png",
-    "manuals/benchmarking/randomized_benchmarking": "_images/randomized_benchmarking_3_1.png",
+    "manuals/verification/randomized_benchmarking": "_images/randomized_benchmarking_3_1.png",
     "manuals/measurement/restless_measurements": "_images/restless_shots.png",
-    "manuals/benchmarking/state_tomography": "_images/state_tomography_3_0.png",
+    "manuals/verification/state_tomography": "_images/state_tomography_3_0.png",
     "manuals/characterization/t1": "_images/t1_0_0.png",
     "manuals/characterization/t2ramsey": "_images/t2ramsey_4_0.png",
     "manuals/characterization/tphi": "_images/tphi_5_1.png",
@@ -121,11 +107,7 @@
 # strings that are used for format of figure numbers. As a special character,
 # %s will be replaced to figure number.
 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 = "en"
 
 # List of patterns, relative to source directory, that match files and
@@ -185,9 +167,6 @@
 
 if os.getenv("EXPERIMENTS_DEV_DOCS", None):
     rst_prolog = """
-.. raw:: html
-
-    <br><br><br>
 .. 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

docs/howtos/cloud_service.rst

@@ -36,7 +36,7 @@ backend and not a simulator to be able to save the experiment data. This is done
 
     t1_delays = np.arange(1e-6, 600e-6, 50e-6)
 
-    exp = T1(qubit=0, delays=t1_delays)
+    exp = T1(physical_qubits=(0,), delays=t1_delays)
 
     t1_expdata = exp.run(backend=backend).block_for_results()
     t1_expdata.save()
@@ -131,7 +131,7 @@ The :meth:`~.ExperimentData.auto_save` feature automatically saves changes to th
 
 .. jupyter-input::
 
-    exp = T1(qubit=0, delays=t1_delays)
+    exp = T1(physical_qubits=(0,), delays=t1_delays)
 
     t1_expdata = exp.run(backend=backend, shots=1000)
     t1_expdata.auto_save = True

docs/howtos/job_splitting.rst

@@ -15,7 +15,7 @@ You can set the ``max_circuits`` option manually when running an experiment:
 
 .. jupyter-input::
 
-    exp = Experiment([0])
+    exp = Experiment((0,))
     exp.set_experiment_options(max_circuits=100)
 
 The experiment class will split its circuits into jobs such that no job has more than