Documentation fixes and formatting

.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
 
@@ -22,5 +21,4 @@ PR comments.
 - [ ] 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, 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