Show missing type hints & inline class base class in API docs (#13483) (

#13516)

* Show missing type hints & inline class values in API docs

* Fix fmt, oops

* Fix density matrix use of Circuit

(cherry picked from commit cc30af5)

Co-authored-by: Eric Arellano <[email protected]>

docs/conf.py

@@ -102,14 +102,21 @@
 # documentation created by autosummary uses a template file (in autosummary in the templates path),
 # which likely overrides the autodoc defaults.
 
+# These options impact when using `.. autoclass::` manually.
+# They do not impact the `.. autosummary::` templates.
+autodoc_default_options = {
+    "show-inheritance": True,
+}
+
 # Move type hints from signatures to the parameter descriptions (except in overload cases, where
 # that's not possible).
 autodoc_typehints = "description"
-# Only add type hints from signature to description body if the parameter has documentation.  The
-# return type is always added to the description (if in the signature).
-autodoc_typehints_description_target = "documented_params"
-
 autoclass_content = "both"
+# Some type hints are too long to be understandable. So, we set up aliases to be used instead.
+autodoc_type_aliases = {
+    "EstimatorPubLike": "EstimatorPubLike",
+    "SamplerPubLike": "SamplerPubLike",
+}
 
 autosummary_generate = True
 autosummary_generate_overwrite = False

qiskit/quantum_info/operators/channel/chi.py

@@ -18,6 +18,8 @@
 from __future__ import annotations
 import copy as _copy
 import math
+from typing import TYPE_CHECKING
+
 import numpy as np
 
 from qiskit import _numpy_compat
@@ -31,6 +33,9 @@
 from qiskit.quantum_info.operators.mixins import generate_apidocs
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
+if TYPE_CHECKING:
+    from qiskit import circuit
+
 
 class Chi(QuantumChannel):
     r"""Pauli basis Chi-matrix representation of a quantum channel.
@@ -59,21 +64,16 @@ class Chi(QuantumChannel):
 
     def __init__(
         self,
-        data: QuantumCircuit | Instruction | BaseOperator | np.ndarray,
+        data: QuantumCircuit | circuit.instruction.Instruction | BaseOperator | np.ndarray,
         input_dims: int | tuple | None = None,
         output_dims: int | tuple | None = None,
     ):
         """Initialize a quantum channel Chi-matrix operator.
 
         Args:
-            data (QuantumCircuit or
-                  Instruction or
-                  BaseOperator or
-                  matrix): data to initialize superoperator.
-            input_dims (tuple): the input subsystem dimensions.
-                                [Default: None]
-            output_dims (tuple): the output subsystem dimensions.
-                                 [Default: None]
+            data: data to initialize superoperator.
+            input_dims: the input subsystem dimensions.
+            output_dims: the output subsystem dimensions.
 
         Raises:
             QiskitError: if input data is not an N-qubit channel or

qiskit/quantum_info/operators/channel/choi.py

@@ -18,6 +18,8 @@
 from __future__ import annotations
 import copy as _copy
 import math
+from typing import TYPE_CHECKING
+
 import numpy as np
 
 from qiskit import _numpy_compat
@@ -32,6 +34,9 @@
 from qiskit.quantum_info.operators.mixins import generate_apidocs
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
+if TYPE_CHECKING:
+    from qiskit import circuit
+
 
 class Choi(QuantumChannel):
     r"""Choi-matrix representation of a Quantum Channel.
@@ -64,21 +69,16 @@ class Choi(QuantumChannel):
 
     def __init__(
         self,
-        data: QuantumCircuit | Instruction | BaseOperator | np.ndarray,
+        data: QuantumCircuit | circuit.instruction.Instruction | BaseOperator | np.ndarray,
         input_dims: int | tuple | None = None,
         output_dims: int | tuple | None = None,
     ):
         """Initialize a quantum channel Choi matrix operator.
 
         Args:
-            data (QuantumCircuit or
-                  Instruction or
-                  BaseOperator or
-                  matrix): data to initialize superoperator.
-            input_dims (tuple): the input subsystem dimensions.
-                                [Default: None]
-            output_dims (tuple): the output subsystem dimensions.
-                                 [Default: None]
+            data: data to initialize superoperator.
+            input_dims: the input subsystem dimensions.
+            output_dims: the output subsystem dimensions.
 
         Raises:
             QiskitError: if input data cannot be initialized as a

qiskit/quantum_info/operators/channel/ptm.py

@@ -18,6 +18,8 @@
 from __future__ import annotations
 import copy as _copy
 import math
+from typing import TYPE_CHECKING
+
 import numpy as np
 
 from qiskit import _numpy_compat
@@ -30,6 +32,9 @@
 from qiskit.quantum_info.operators.mixins import generate_apidocs
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
+if TYPE_CHECKING:
+    from qiskit import circuit
+
 
 class PTM(QuantumChannel):
     r"""Pauli Transfer Matrix (PTM) representation of a Quantum Channel.
@@ -67,21 +72,16 @@ class PTM(QuantumChannel):
 
     def __init__(
         self,
-        data: QuantumCircuit | Instruction | BaseOperator | np.ndarray,
+        data: QuantumCircuit | circuit.instruction.Instruction | BaseOperator | np.ndarray,
         input_dims: int | tuple | None = None,
         output_dims: int | tuple | None = None,
     ):
         """Initialize a PTM quantum channel operator.
 
         Args:
-            data (QuantumCircuit or
-                  Instruction or
-                  BaseOperator or
-                  matrix): data to initialize superoperator.
-            input_dims (tuple): the input subsystem dimensions.
-                                [Default: None]
-            output_dims (tuple): the output subsystem dimensions.
-                                 [Default: None]
+            data: data to initialize superoperator.
+            input_dims: the input subsystem dimensions.
+            output_dims: the output subsystem dimensions.
 
         Raises:
             QiskitError: if input data is not an N-qubit channel or

qiskit/quantum_info/operators/channel/quantum_channel.py

@@ -53,9 +53,9 @@ def __init__(
         """Initialize a quantum channel Superoperator operator.
 
         Args:
-            data (array or list): quantum channel data array.
-            op_shape (OpShape): the operator shape of the channel.
-            num_qubits (int): the number of qubits if the channel is N-qubit.
+            data: quantum channel data array.
+            op_shape: the operator shape of the channel.
+            num_qubits: the number of qubits if the channel is N-qubit.
 
         Raises:
             QiskitError: if arguments are invalid.

qiskit/quantum_info/operators/channel/stinespring.py

@@ -17,6 +17,8 @@
 import copy
 import math
 from numbers import Number
+from typing import TYPE_CHECKING
+
 import numpy as np
 
 from qiskit.circuit.quantumcircuit import QuantumCircuit
@@ -32,6 +34,9 @@
 from qiskit.quantum_info.operators.mixins import generate_apidocs
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
+if TYPE_CHECKING:
+    from qiskit import circuit
+
 
 class Stinespring(QuantumChannel):
     r"""Stinespring representation of a quantum channel.
@@ -64,21 +69,16 @@ class Stinespring(QuantumChannel):
 
     def __init__(
         self,
-        data: QuantumCircuit | Instruction | BaseOperator | np.ndarray,
+        data: QuantumCircuit | circuit.instruction.Instruction | BaseOperator | np.ndarray,
         input_dims: int | tuple | None = None,
         output_dims: int | tuple | None = None,
     ):
         """Initialize a quantum channel Stinespring operator.
 
         Args:
-            data (QuantumCircuit or
-                  Instruction or
-                  BaseOperator or
-                  matrix): data to initialize superoperator.
-            input_dims (tuple): the input subsystem dimensions.
-                                [Default: None]
-            output_dims (tuple): the output subsystem dimensions.
-                                 [Default: None]
+            data: data to initialize superoperator.
+            input_dims: the input subsystem dimensions.
+            output_dims: the output subsystem dimensions.
 
         Raises:
             QiskitError: if input data cannot be initialized as a

qiskit/quantum_info/operators/channel/superop.py

@@ -33,6 +33,7 @@
 from qiskit.quantum_info.operators.operator import Operator
 
 if TYPE_CHECKING:
+    from qiskit import circuit
     from qiskit.quantum_info.states.densitymatrix import DensityMatrix
     from qiskit.quantum_info.states.statevector import Statevector
 
@@ -62,21 +63,16 @@ class SuperOp(QuantumChannel):
 
     def __init__(
         self,
-        data: QuantumCircuit | Instruction | BaseOperator | np.ndarray,
+        data: QuantumCircuit | circuit.instruction.Instruction | BaseOperator | np.ndarray,
         input_dims: tuple | None = None,
         output_dims: tuple | None = None,
     ):
         """Initialize a quantum channel Superoperator operator.
 
         Args:
-            data (QuantumCircuit or
-                  Instruction or
-                  BaseOperator or
-                  matrix): data to initialize superoperator.
-            input_dims (tuple): the input subsystem dimensions.
-                                [Default: None]
-            output_dims (tuple): the output subsystem dimensions.
-                                 [Default: None]
+            data: data to initialize superoperator.
+            input_dims: the input subsystem dimensions.
+            output_dims: the output subsystem dimensions.
 
         Raises:
             QiskitError: if input data cannot be initialized as a

qiskit/quantum_info/states/densitymatrix.py

@@ -17,6 +17,8 @@
 from __future__ import annotations
 import copy as _copy
 from numbers import Number
+from typing import TYPE_CHECKING
+
 import numpy as np
 
 from qiskit import _numpy_compat
@@ -37,27 +39,27 @@
 from qiskit._accelerate.pauli_expval import density_expval_pauli_no_x, density_expval_pauli_with_x
 from qiskit.quantum_info.states.statevector import Statevector
 
+if TYPE_CHECKING:
+    from qiskit import circuit
+
 
 class DensityMatrix(QuantumState, TolerancesMixin):
     """DensityMatrix class"""
 
     def __init__(
         self,
-        data: np.ndarray | list | QuantumCircuit | Instruction | QuantumState,
+        data: np.ndarray | list | QuantumCircuit | circuit.instruction.Instruction | QuantumState,
         dims: int | tuple | list | None = None,
     ):
         """Initialize a density matrix object.
 
         Args:
-            data (np.ndarray or list or matrix_like or QuantumCircuit or
-                  qiskit.circuit.Instruction):
-                A statevector, quantum instruction or an object with a ``to_operator`` or
+            data: A statevector, quantum instruction or an object with a ``to_operator`` or
                 ``to_matrix`` method from which the density matrix can be constructed.
                 If a vector the density matrix is constructed as the projector of that vector.
                 If a quantum instruction, the density matrix is constructed by assuming all
                 qubits are initialized in the zero state.
-            dims (int or tuple or list): Optional. The subsystem dimension
-                    of the state (See additional information).
+            dims: The subsystem dimension of the state (See additional information).
 
         Raises:
             QiskitError: if input data is not valid.
@@ -303,19 +305,17 @@ def _multiply(self, other):
 
     def evolve(
         self,
-        other: Operator | QuantumChannel | Instruction | QuantumCircuit,
+        other: Operator | QuantumChannel | circuit.instruction.Instruction | QuantumCircuit,
         qargs: list[int] | None = None,
     ) -> DensityMatrix:
         """Evolve a quantum state by an operator.
 
         Args:
-            other (Operator or QuantumChannel
-                   or Instruction or Circuit): The operator to evolve by.
-            qargs (list): a list of QuantumState subsystem positions to apply
-                           the operator on.
+            other: The operator to evolve by.
+            qargs: a list of QuantumState subsystem positions to apply the operator on.
 
         Returns:
-            DensityMatrix: the output density matrix.
+            The output density matrix.
 
         Raises:
             QiskitError: if the operator dimension does not match the
@@ -598,18 +598,20 @@ def from_int(i: int, dims: int | tuple | list) -> DensityMatrix:
         return DensityMatrix(state, dims=dims)
 
     @classmethod
-    def from_instruction(cls, instruction: Instruction | QuantumCircuit) -> DensityMatrix:
+    def from_instruction(
+        cls, instruction: circuit.instruction.Instruction | QuantumCircuit
+    ) -> DensityMatrix:
         """Return the output density matrix of an instruction.
 
         The statevector is initialized in the state :math:`|{0,\\ldots,0}\\rangle` of
         the same number of qubits as the input instruction or circuit, evolved
         by the input instruction, and the output statevector returned.
 
         Args:
-            instruction (qiskit.circuit.Instruction or QuantumCircuit): instruction or circuit
+            instruction: instruction or circuit
 
         Returns:
-            DensityMatrix: the final density matrix.
+            The final density matrix.
 
         Raises:
             QiskitError: if the instruction contains invalid instructions for

qiskit/quantum_info/states/stabilizerstate.py

@@ -17,6 +17,7 @@
 from __future__ import annotations
 
 from collections.abc import Collection
+from typing import TYPE_CHECKING
 
 import numpy as np
 
@@ -28,6 +29,9 @@
 from qiskit.quantum_info.states.quantum_state import QuantumState
 from qiskit.circuit import QuantumCircuit, Instruction
 
+if TYPE_CHECKING:
+    from qiskit import circuit
+
 
 class StabilizerState(QuantumState):
     """StabilizerState class.
@@ -79,17 +83,14 @@ class StabilizerState(QuantumState):
 
     def __init__(
         self,
-        data: StabilizerState | Clifford | Pauli | QuantumCircuit | Instruction,
+        data: StabilizerState | Clifford | Pauli | QuantumCircuit | circuit.instruction.Instruction,
         validate: bool = True,
     ):
         """Initialize a StabilizerState object.
 
         Args:
-            data (StabilizerState or Clifford or Pauli or QuantumCircuit or
-                  qiskit.circuit.Instruction):
-                Data from which the stabilizer state can be constructed.
-            validate (boolean): validate that the stabilizer state data is
-                a valid Clifford.
+            data: Data from which the stabilizer state can be constructed.
+            validate: validate that the stabilizer state data is a valid Clifford.
         """
 
         # Initialize from another StabilizerState