Merge remote-tracking branch 'origin/stable/0.25' into backport-meta-docs

Author: mtreinish

docs/apidoc/exceptions.rst

@@ -0,0 +1,6 @@
+.. _qiskit-exceptions:
+
+.. automodule:: qiskit.exceptions
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidoc/index.rst

@@ -45,3 +45,4 @@ API Reference
    utils_mitigation
    opflow
    algorithms
+   exceptions

qiskit/algorithms/amplitude_estimators/ae.py

@@ -458,7 +458,6 @@ def compute_confidence_interval(
             The (1 - alpha) confidence interval of the specified kind.
 
         Raises:
-            AquaError: If 'mle' is not in self._ret.keys() (i.e. `run` was not called yet).
             NotImplementedError: If the confidence interval method `kind` is not implemented.
         """
         # if statevector simulator the estimate is exact

qiskit/circuit/__init__.py

@@ -348,7 +348,17 @@
 .. currentmodule:: qiskit.circuit.random
 .. autofunction:: random_circuit
 .. currentmodule:: qiskit.circuit
+
+Exceptions
+----------
+
+Almost all circuit functions and methods will raise a :exc:`CircuitError` when encountering an error
+that is particular to usage of Qiskit (as opposed to regular typing or indexing problems, which will
+typically raise the corresponding standard Python error).
+
+.. autoexception:: CircuitError
 """
+from .exceptions import CircuitError
 from .quantumcircuit import QuantumCircuit
 from .classicalregister import ClassicalRegister, Clbit
 from .quantumregister import QuantumRegister, Qubit, AncillaRegister, AncillaQubit

qiskit/circuit/exceptions.py

@@ -17,5 +17,3 @@
 
 class CircuitError(QiskitError):
     """Base class for errors raised while processing a circuit."""
-
-    pass

qiskit/dagcircuit/__init__.py

@@ -34,10 +34,8 @@
 Exceptions
 ==========
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   DAGCircuitError
+.. autoexception:: DAGCircuitError
+.. autoexception:: DAGDependencyError
 
 Utilities
 =========
@@ -53,5 +51,5 @@
 from .dagcircuit import DAGCircuit
 from .dagnode import DAGNode, DAGOpNode, DAGInNode, DAGOutNode
 from .dagdepnode import DAGDepNode
-from .exceptions import DAGCircuitError
+from .exceptions import DAGCircuitError, DAGDependencyError
 from .dagdependency import DAGDependency

qiskit/exceptions.py

@@ -10,7 +10,39 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Exceptions for errors raised by Qiskit."""
+"""
+===============================================
+Top-level exceptions (:mod:`qiskit.exceptions`)
+===============================================
+
+All Qiskit-related errors raised by Qiskit are subclasses of the base:
+
+.. autoexception:: QiskitError
+
+.. note::
+
+    Errors that are just general programming errors, such as incorrect typing, may still raise
+    standard Python errors such as ``TypeError``.  :exc:`QiskitError` is generally for errors raised
+    in usage that is particular to Qiskit.
+
+Many of the Qiskit subpackages define their own more granular error, to help in catching only the
+subset of errors you care about.  For example, :mod:`qiskit.circuit` almost exclusively uses
+:exc:`.CircuitError`, while both :exc:`.QASM2ExportError` and :exc:`.QASM2ParseError` derive from
+:exc:`.QASM2Error` in :mod:`qiskit.qasm2`, which is in turn a type of :exc:`.QiskitError`.
+
+Qiskit has several optional features that depend on other packages that are not required for a
+minimal install.  You can read more about those, and ways to check for their presence, in
+:mod:`qiskit.utils.optionals`.  Trying to use a feature that requires an optional extra will raise a
+particular error, which subclasses both :exc:`QiskitError` and the Python built-in ``ImportError``.
+
+.. autoexception:: MissingOptionalLibraryError
+
+Two more uncommon errors relate to failures in reading user-configuration files, or specifying a
+filename that cannot be used:
+
+.. autoexception:: QiskitUserConfigError
+.. autoexception:: InvalidFileError
+"""
 
 from typing import Optional
 

qiskit/extensions/__init__.py

@@ -53,12 +53,21 @@
    UCRXGate
    UCRYGate
    UCRZGate
+
+Exceptions
+==========
+
+The additional gates in this module will tend to raise a custom exception when they encounter
+problems.
+
+.. autoexception:: ExtensionError
 """
 
 # import all standard gates
 from qiskit.circuit.library.standard_gates import *
 from qiskit.circuit.barrier import Barrier
 
+from .exceptions import ExtensionError
 from .quantum_initializer import (
     Initialize,
     SingleQubitUnitary,

qiskit/opflow/gradients/circuit_gradients/lin_comb.py

@@ -712,7 +712,7 @@ def _gradient_states(
             parameterized gates to compute the product rule.
 
         Raises:
-            AquaError: If one of the circuits could not be constructed.
+            QiskitError: If one of the circuits could not be constructed.
             TypeError: If the operators is of unsupported type.
             ValueError: If the auxiliary operator preparation fails.
         """
@@ -804,7 +804,7 @@ def _hessian_states(
             created per parameterized gates to compute the product rule.
 
         Raises:
-            AquaError: If one of the circuits could not be constructed.
+            QiskitError: If one of the circuits could not be constructed.
             TypeError: If ``operator`` is of unsupported type.
             ValueError: If the auxiliary operator preparation fails.
         """

qiskit/providers/__init__.py

@@ -129,6 +129,7 @@
 .. autoexception:: BackendPropertyError
 .. autoexception:: JobError
 .. autoexception:: JobTimeoutError
+.. autoexception:: BackendConfigurationError
 
 ======================
 Writing a New Provider