[Suggestion] Use .. plot:: directive to test code examples

crates/circuit/src/circuit_data.rs

@@ -56,7 +56,9 @@ import_exception!(qiskit.circuit.exceptions, CircuitError);
 ///
 /// For example,
 ///
-/// .. code-block::
+/// .. plot::
+///    :include-source:
+///    :no-figs:
 ///
 ///     qubits = [Qubit()]
 ///     data = CircuitData(qubits)

qiskit/assembler/assemble_circuits.py

@@ -429,7 +429,9 @@ def assemble_circuits(
 
     Examples:
 
-        .. code-block:: python
+        .. plot::
+           :include-source:
+           :nofigs:
 
             from qiskit.circuit import QuantumRegister, ClassicalRegister, QuantumCircuit
             from qiskit.assembler import assemble_circuits

qiskit/assembler/assemble_schedules.py

@@ -52,7 +52,9 @@ def assemble_schedules(
 
     Examples:
 
-        .. code-block:: python
+        .. plot::
+           :include-source:
+           :nofigs:
 
             from qiskit import pulse
             from qiskit.assembler import assemble_schedules

qiskit/assembler/disassemble.py

@@ -69,7 +69,9 @@ def disassemble(qobj) -> Union[CircuitModule, PulseModule]:
 
     Examples:
 
-        .. code-block:: python
+        .. plot::
+           :include-source:
+           :nofigs:
 
             from qiskit.circuit import QuantumRegister, ClassicalRegister, QuantumCircuit
             from qiskit.compiler.assembler import assemble

qiskit/circuit/__init__.py

@@ -559,7 +559,11 @@
 
 The :class:`Barrier` instruction can span an arbitrary number of qubits and clbits, and is a no-op
 in hardware.  During transpilation and optimization, however, it blocks any optimizations from
-"crossing" the barrier; that is, in::
+"crossing" the barrier; that is, in:
+
+.. plot::
+    :include-source:
+    :nofigs:
 
     from qiskit.circuit import QuantumCircuit
 

qiskit/circuit/classical/types/ordering.py

@@ -205,7 +205,10 @@ def cast_kind(from_: Type, to_: Type, /) -> CastKind:
 
     Examples:
 
-        .. code-block:: python
+        .. plot::
+           :include-source:
+           :nofigs:
+
 
             >>> from qiskit.circuit.classical import types
             >>> types.cast_kind(types.Bool(), types.Bool())

qiskit/circuit/classicalfunction/__init__.py

@@ -25,7 +25,7 @@
 how to synthesize a simple boolean function defined using Python into a
 QuantumCircuit:
 
-   .. code-block::
+  .. code-block:: python
 
       from qiskit.circuit.classicalfunction import classical_function
       from qiskit.circuit.classicalfunction.types import Int1
@@ -37,6 +37,8 @@ def grover_oracle(a: Int1, b: Int1, c: Int1, d: Int1) -> Int1:
       quantum_circuit = grover_oracle.synth(registerless=False)
       quantum_circuit.draw('text')
 
+  .. code-block:: text
+
            a: ──o──
                 │
            b: ──■──

qiskit/circuit/library/__init__.py

@@ -48,7 +48,9 @@
 
 For example:
 
-.. code-block::
+.. plot::
+   :include-source:
+   :nofigs:
 
     from qiskit.circuit.library import XGate
     gate = XGate()
@@ -150,7 +152,9 @@
 set the amount of qubits involved at instantiation time.
 
 
-.. code-block::
+.. plot::
+   :include-source:
+   :nofigs:
 
     from qiskit.circuit.library import Diagonal
 
@@ -372,7 +376,9 @@
 
 In this example, the identity constant in a template is checked:
 
-.. code-block::
+.. plot::
+   :include-source:
+   :nofigs:
 
     from qiskit.circuit.library.templates import template_nct_4b_1
     from qiskit.quantum_info import Operator

qiskit/circuit/library/generalized_gates/unitary.py

@@ -45,7 +45,9 @@ class UnitaryGate(Gate):
         quantum circuit. The matrix can also be directly applied to the quantum
         circuit, see :meth:`.QuantumCircuit.unitary`.
 
-        .. code-block:: python
+        .. plot::
+           :include-source:
+           :nofigs:
 
             from qiskit import QuantumCircuit
             from qiskit.circuit.library import UnitaryGate

qiskit/circuit/library/pauli_evolution.py

@@ -48,7 +48,9 @@ class PauliEvolutionGate(Gate):
 
     **Examples:**
 
-    .. code-block:: python
+    .. plot::
+       :include-source:
+       :nofigs:
 
         from qiskit.circuit import QuantumCircuit
         from qiskit.circuit.library import PauliEvolutionGate
@@ -67,7 +69,9 @@ class PauliEvolutionGate(Gate):
         circuit.append(evo, range(2))
         print(circuit.draw())
 
-    The above will print (note that the ``-0.1`` coefficient is not printed!)::
+    The above will print (note that the ``-0.1`` coefficient is not printed!):
+
+    .. code-block:: text
 
              ┌──────────────────────────┐
         q_0: ┤0                         ├

qiskit/circuit/quantumcircuit.py

@@ -3854,7 +3854,10 @@ def measure(self, qubit: QubitSpecifier, cbit: ClbitSpecifier) -> InstructionSet
             In this example, a qubit is measured and the result of that measurement is stored in the
             classical bit (usually expressed in diagrams as a double line):
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
+               :context: reset
 
                from qiskit import QuantumCircuit
                circuit = QuantumCircuit(1, 1)
@@ -3874,12 +3877,18 @@ def measure(self, qubit: QubitSpecifier, cbit: ClbitSpecifier) -> InstructionSet
             It is possible to call ``measure`` with lists of ``qubits`` and ``cbits`` as a shortcut
             for one-to-one measurement. These two forms produce identical results:
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
+               :context:
 
                circuit = QuantumCircuit(2, 2)
                circuit.measure([0,1], [0,1])
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
+               :context:
 
                circuit = QuantumCircuit(2, 2)
                circuit.measure(0, 0)
@@ -3888,7 +3897,10 @@ def measure(self, qubit: QubitSpecifier, cbit: ClbitSpecifier) -> InstructionSet
             Instead of lists, you can use :class:`~qiskit.circuit.QuantumRegister` and
             :class:`~qiskit.circuit.ClassicalRegister` under the same logic.
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
+               :context: reset
 
                 from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
                 qreg = QuantumRegister(2, "qreg")
@@ -3898,7 +3910,10 @@ def measure(self, qubit: QubitSpecifier, cbit: ClbitSpecifier) -> InstructionSet
 
             This is equivalent to:
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
+               :context:
 
                 circuit = QuantumCircuit(qreg, creg)
                 circuit.measure(qreg[0], creg[0])
@@ -4147,7 +4162,9 @@ def parameters(self) -> ParameterView:
 
             The snippet below shows that insertion order of parameters does not matter.
 
-            .. code-block:: python
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 >>> from qiskit.circuit import QuantumCircuit, Parameter
                 >>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant")
@@ -4161,7 +4178,9 @@ def parameters(self) -> ParameterView:
             Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers.
             The literal "10" comes before "2" in strict alphabetical sorting.
 
-            .. code-block:: python
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 >>> from qiskit.circuit import QuantumCircuit, Parameter
                 >>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")]
@@ -4176,7 +4195,9 @@ def parameters(self) -> ParameterView:
 
             To respect numerical sorting, a :class:`.ParameterVector` can be used.
 
-            .. code-block:: python
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 >>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector
                 >>> x = ParameterVector("x", 12)
@@ -5680,7 +5701,9 @@ def prepare_state(
         Examples:
             Prepare a qubit in the state :math:`(|0\rangle - |1\rangle) / \sqrt{2}`.
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 import numpy as np
                 from qiskit import QuantumCircuit
@@ -5703,7 +5726,9 @@ def prepare_state(
             More information about labels for basis states are in
             :meth:`.Statevector.from_label`.
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 import numpy as np
                 from qiskit import QuantumCircuit
@@ -5724,7 +5749,10 @@ def prepare_state(
 
 
             Initialize two qubits from an array of complex amplitudes
-            .. code-block::
+
+            .. plot::
+                :include-source:
+                :nofigs:
 
                 import numpy as np
                 from qiskit import QuantumCircuit
@@ -5795,7 +5823,9 @@ class to prepare the qubits in a specified state.
         Examples:
             Prepare a qubit in the state :math:`(|0\rangle - |1\rangle) / \sqrt{2}`.
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 import numpy as np
                 from qiskit import QuantumCircuit
@@ -5818,7 +5848,9 @@ class to prepare the qubits in a specified state.
             More information about labels for basis states are in
             :meth:`.Statevector.from_label`.
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 import numpy as np
                 from qiskit import QuantumCircuit
@@ -5839,7 +5871,9 @@ class to prepare the qubits in a specified state.
 
             Initialize two qubits from an array of complex amplitudes.
 
-            .. code-block::
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 import numpy as np
                 from qiskit import QuantumCircuit
@@ -5890,7 +5924,9 @@ def unitary(
 
             Apply a gate specified by a unitary matrix to a quantum circuit
 
-            .. code-block:: python
+            .. plot::
+               :include-source:
+               :nofigs:
 
                 from qiskit import QuantumCircuit
                 matrix = [[0, 0, 0, 1],

qiskit/converters/circuit_to_dag.py

@@ -41,7 +41,9 @@ def circuit_to_dag(circuit, copy_operations=True, *, qubit_order=None, clbit_ord
             the circuit.
 
     Example:
-        .. code-block::
+        .. plot::
+            :include-source:
+            :nofigs:
 
             from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
             from qiskit.dagcircuit import DAGCircuit

qiskit/converters/circuit_to_instruction.py

@@ -43,7 +43,9 @@ def circuit_to_instruction(circuit, parameter_map=None, equivalence_library=None
         yield the components comprising the original circuit.
 
     Example:
-        .. code-block::
+        .. plot::
+            :include-source:
+            :nofigs:
 
             from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
             from qiskit.converters import circuit_to_instruction