Some doc formatting and link, mostly on quantumcircuit.py file (#9771)

* some doc formating and link, mostly on quantumcircuit.py file

* Update qiskit/circuit/quantumcircuit.py

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* ident

* more typos

* more typos

* another iteration

* Bit and Register

* notes on Register and Bit

* Update qiskit/circuit/bit.py

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

* Update qiskit/circuit/register.py

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

---------

Co-authored-by: Julien Gacon <gaconju@gmail.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
(cherry picked from commit b4bc559)

qiskit/algorithms/optimizers/qnspsa.py

@@ -277,7 +277,7 @@ def get_fidelity(
             F(\theta, \phi) = \big|\langle 0 | U^\dagger(\theta) U(\phi) |0\rangle  \big|^2.
 
         The output of this function can be used as input for the ``fidelity`` to the
-        :class:~`qiskit.algorithms.optimizers.QNSPSA` optimizer.
+        :class:`~.QNSPSA` optimizer.
 
         Args:
             circuit: The circuit preparing the parameterized ansatz.

qiskit/circuit/__init__.py

@@ -263,6 +263,8 @@
    AncillaRegister
    AncillaQubit
    CircuitInstruction
+   Register
+   Bit
 
 Gates and Instructions
 ----------------------
@@ -328,6 +330,8 @@
 from .parameterexpression import ParameterExpression
 from .quantumcircuitdata import CircuitInstruction
 from .equivalence import EquivalenceLibrary
+from .bit import Bit
+from .register import Register
 from . import library
 from .commutation_checker import CommutationChecker
 

qiskit/circuit/bit.py

@@ -19,7 +19,13 @@
 
 
 class Bit:
-    """Implement a generic bit."""
+    """Implement a generic bit.
+
+    .. note::
+        This class should not be instantiated directly. This is just a superclass
+        for :class:`~.Clbit` and :class:`~.Qubit`.
+
+    """
 
     __slots__ = {"_register", "_index", "_hash", "_repr"}
 

qiskit/circuit/controlflow/for_loop.py

@@ -142,7 +142,7 @@ class ForLoopContext:
         from qiskit import QuantumCircuit
         qc = QuantumCircuit(2, 1)
 
-        with qc.for_loop(None, range(5)) as i:
+        with qc.for_loop(range(5)) as i:
             qc.rx(i * math.pi/4, 0)
             qc.cx(0, 1)
             qc.measure(0, 0)

qiskit/circuit/instruction.py

@@ -417,12 +417,11 @@ def copy(self, name=None):
         Copy of the instruction.
 
         Args:
-          name (str): name to be given to the copied circuit,
-            if None then the name stays the same.
+            name (str): name to be given to the copied circuit, if ``None`` then the name stays the same.
 
         Returns:
-          qiskit.circuit.Instruction: a copy of the current instruction, with the name
-            updated if it was provided
+            qiskit.circuit.Instruction: a copy of the current instruction, with the name updated if it
+            was provided
         """
         cpy = self.__deepcopy__()
 

qiskit/circuit/instructionset.py

@@ -95,14 +95,14 @@ class InstructionSet:
     def __init__(self, circuit_cregs=None, *, resource_requester: Optional[Callable] = None):
         """New collection of instructions.
 
-        The context (qargs and cargs that each instruction is attached to) is also stored separately
-        for each instruction.
+        The context (``qargs`` and ``cargs`` that each instruction is attached to) is also stored
+        separately for each instruction.
 
         Args:
-            circuit_cregs (list[ClassicalRegister]): Optional. List of cregs of the
+            circuit_cregs (list[ClassicalRegister]): Optional. List of ``cregs`` of the
                 circuit to which the instruction is added. Default: `None`.
 
-                .. deprecated:: qiskit-terra 0.19
+                .. deprecated:: 0.19
                     The classical registers are insufficient to access all classical resources in a
                     circuit, as there may be loose classical bits as well.  It can also cause
                     integer indices to be resolved incorrectly if any registers overlap.  Instead,

qiskit/circuit/quantumcircuit.py

@@ -130,11 +130,11 @@ class QuantumCircuit:
     A circuit is a list of instructions bound to some registers.
 
     Args:
-        regs (list(:class:`Register`) or list(``int``) or list(list(:class:`Bit`))): The
+        regs (list(:class:`~.Register`) or list(``int``) or list(list(:class:`~.Bit`))): The
             registers to be included in the circuit.
 
-            * If a list of :class:`Register` objects, represents the :class:`QuantumRegister`
-              and/or :class:`ClassicalRegister` objects to include in the circuit.
+            * If a list of :class:`~.Register` objects, represents the :class:`.QuantumRegister`
+              and/or :class:`.ClassicalRegister` objects to include in the circuit.
 
               For example:
 
@@ -151,8 +151,8 @@ class QuantumCircuit:
                 * ``QuantumCircuit(4) # A QuantumCircuit with 4 qubits``
                 * ``QuantumCircuit(4, 3) # A QuantumCircuit with 4 qubits and 3 classical bits``
 
-            * If a list of python lists containing :class:`Bit` objects, a collection of
-              :class:`Bit` s to be added to the circuit.
+            * If a list of python lists containing :class:`.Bit` objects, a collection of
+              :class:`.Bit` s to be added to the circuit.
 
 
         name (str): the name of the quantum circuit. If not set, an
@@ -1217,8 +1217,7 @@ def append(
             were actually added to the circuit.
 
         Raises:
-            CircuitError: if the operation passed is not an instance of
-                :class:`~.circuit..Instruction`.
+            CircuitError: if the operation passed is not an instance of :class:`~.circuit.Instruction` .
         """
         if isinstance(instruction, CircuitInstruction):
             operation = instruction.operation
@@ -1855,10 +1854,10 @@ def draw(
                 Default is True, except for when ``output`` is set to  ``"text"``.
             wire_order (list): Optional. A list of integers used to reorder the display
                 of the bits. The list must have an entry for every bit with the bits
-                in the range 0 to (num_qubits + num_clbits).
+                in the range 0 to (``num_qubits`` + ``num_clbits``).
 
         Returns:
-            :class:`TextDrawing` or :class:`matplotlib.figure` or :class:`PIL.Image` or
+            :class:`.TextDrawing` or :class:`matplotlib.figure` or :class:`PIL.Image` or
             :class:`str`:
 
             * `TextDrawing` (output='text')
@@ -2860,8 +2859,8 @@ def _rebind_definition(
                         self._rebind_definition(inner.operation, parameter, value)
 
     def barrier(self, *qargs: QubitSpecifier, label=None) -> InstructionSet:
-        """Apply :class:`~qiskit.circuit.Barrier`. If qargs is empty, applies to all qubits in the
-        circuit.
+        """Apply :class:`~.library.Barrier`. If ``qargs`` is empty, applies to all qubits
+        in the circuit.
 
         Args:
             qargs (QubitSpecifier): Specification for one or more qubit arguments.
@@ -2897,14 +2896,15 @@ def delay(
         qarg: Optional[QubitSpecifier] = None,
         unit: str = "dt",
     ) -> InstructionSet:
-        """Apply :class:`~qiskit.circuit.Delay`. If qarg is None, applies to all qubits.
+        """Apply :class:`~.circuit.Delay`. If qarg is ``None``, applies to all qubits.
         When applying to multiple qubits, delays with the same duration will be created.
 
         Args:
             duration (int or float or ParameterExpression): duration of the delay.
             qarg (Object): qubit argument to apply this delay.
-            unit (str): unit of the duration. Supported units: 's', 'ms', 'us', 'ns', 'ps', 'dt'.
-                Default is ``dt``, i.e. integer time unit depending on the target backend.
+            unit (str): unit of the duration. Supported units: ``'s'``, ``'ms'``, ``'us'``,
+                ``'ns'``, ``'ps'``, and ``'dt'``. Default is ``'dt'``, i.e. integer time unit
+                depending on the target backend.
 
         Returns:
             qiskit.circuit.InstructionSet: handle to the added instructions.
@@ -3010,7 +3010,7 @@ def id(self, qubit: QubitSpecifier) -> InstructionSet:  # pylint: disable=invali
         return self.i(qubit)
 
     def ms(self, theta: ParameterValueType, qubits: Sequence[QubitSpecifier]) -> InstructionSet:
-        """Apply :class:`~qiskit.circuit.library.generalized_gates.gms.MSGate`.
+        """Apply :class:`~qiskit.circuit.library.MSGate`.
 
         For the full matrix form of this gate, see the underlying gate documentation.
 
@@ -3131,9 +3131,9 @@ def rv(
         rotation in radians.
 
         Args:
-            vx: x-compenent of the rotation axis.
-            vy: y-compenent of the rotation axis.
-            vz: z-compenent of the rotation axis.
+            vx: x-component of the rotation axis.
+            vy: y-component of the rotation axis.
+            vz: z-component of the rotation axis.
             qubit: The qubit(s) to apply the gate to.
 
         Returns:
@@ -3564,8 +3564,8 @@ def cswap(
             target_qubit2: The qubit(s) targeted by the gate.
             label: The string label of the gate in the circuit.
             ctrl_state:
-                The control state in decimal, or as a bitstring (e.g. '1').  Defaults to controlling
-                on the '1' state.
+                The control state in decimal, or as a bitstring (e.g. ``'1'``).  Defaults to controlling
+                on the ``'1'`` state.
 
         Returns:
             A handle to the instructions created.
@@ -3906,10 +3906,10 @@ def mcx(
         The multi-cX gate can be implemented using different techniques, which use different numbers
         of ancilla qubits and have varying circuit depth. These modes are:
 
-        - 'noancilla': Requires 0 ancilla qubits.
-        - 'recursion': Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0.
-        - 'v-chain': Requires 2 less ancillas than the number of control qubits.
-        - 'v-chain-dirty': Same as for the clean ancillas (but the circuit will be longer).
+        - ``'noancilla'``: Requires 0 ancilla qubits.
+        - ``'recursion'``: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0.
+        - ``'v-chain'``: Requires 2 less ancillas than the number of control qubits.
+        - ``'v-chain-dirty'``: Same as for the clean ancillas (but the circuit will be longer).
 
         For the full matrix form of this gate, see the underlying gate documentation.
 
@@ -3984,10 +3984,10 @@ def mct(
         The multi-cX gate can be implemented using different techniques, which use different numbers
         of ancilla qubits and have varying circuit depth. These modes are:
 
-        - 'noancilla': Requires 0 ancilla qubits.
-        - 'recursion': Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0.
-        - 'v-chain': Requires 2 less ancillas than the number of control qubits.
-        - 'v-chain-dirty': Same as for the clean ancillas (but the circuit will be longer).
+        - ``'noancilla'``: Requires 0 ancilla qubits.
+        - ``'recursion'``: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0.
+        - ``'v-chain'``: Requires 2 less ancillas than the number of control qubits.
+        - ``'v-chain-dirty'``: Same as for the clean ancillas (but the circuit will be longer).
 
         For the full matrix form of this gate, see the underlying gate documentation.
 
@@ -4362,10 +4362,10 @@ def for_loop(
 
         There are two forms for calling this function.  If called with all its arguments (with the
         possible exception of ``label``), it will create a
-        :obj:`~qiskit.circuit.controlflow.ForLoopOp` with the given ``body``.  If ``body`` (and
+        :class:`~qiskit.circuit.ForLoopOp` with the given ``body``.  If ``body`` (and
         ``qubits`` and ``clbits``) are *not* passed, then this acts as a context manager, which,
         when entered, provides a loop variable (unless one is given, in which case it will be
-        reused) and will automatically build a :obj:`~qiskit.circuit.controlflow.ForLoopOp` when the
+        reused) and will automatically build a :class:`~qiskit.circuit.ForLoopOp` when the
         scope finishes.  In this form, you do not need to keep track of the qubits or clbits you are
         using, because the scope will handle it for you.
 
@@ -4460,7 +4460,7 @@ def if_test(
 
         There are two forms for calling this function.  If called with all its arguments (with the
         possible exception of ``label``), it will create a
-        :obj:`~qiskit.circuit.controlflow.IfElseOp` with the given ``true_body``, and there will be
+        :obj:`~qiskit.circuit.IfElseOp` with the given ``true_body``, and there will be
         no branch for the ``false`` condition (see also the :meth:`.if_else` method).  However, if
         ``true_body`` (and ``qubits`` and ``clbits``) are *not* passed, then this acts as a context
         manager, which can be used to build ``if`` statements.  The return value of the ``with``
@@ -4547,7 +4547,7 @@ def if_else(
         clbits: Sequence[ClbitSpecifier],
         label: Optional[str] = None,
     ) -> InstructionSet:
-        """Apply :class:`~qiskit.circuit.controlflow.IfElseOp`.
+        """Apply :class:`~qiskit.circuit.IfElseOp`.
 
         .. note::
 
@@ -4592,7 +4592,7 @@ def if_else(
         return self.append(IfElseOp(condition, true_body, false_body, label), qubits, clbits)
 
     def break_loop(self) -> InstructionSet:
-        """Apply :class:`~qiskit.circuit.controlflow.BreakLoopOp`.
+        """Apply :class:`~qiskit.circuit.BreakLoopOp`.
 
         .. warning::
 
@@ -4622,7 +4622,7 @@ def break_loop(self) -> InstructionSet:
         return self.append(BreakLoopOp(self.num_qubits, self.num_clbits), self.qubits, self.clbits)
 
     def continue_loop(self) -> InstructionSet:
-        """Apply :class:`~qiskit.circuit.controlflow.ContinueLoopOp`.
+        """Apply :class:`~qiskit.circuit.ContinueLoopOp`.
 
         .. warning::
 
@@ -4632,8 +4632,8 @@ def continue_loop(self) -> InstructionSet:
             determined.  This would quickly lead to invalid circuits, and so if you are trying to
             construct a reusable loop body (without the context managers), you must also use the
             non-context-manager form of :meth:`.if_test` and :meth:`.if_else`.  Take care that the
-            :obj:`.ContinueLoopOp` instruction must span all the resources of its containing loop,
-            not just the immediate scope.
+            :class:`~qiskit.circuit.ContinueLoopOp` instruction must span all the resources of its
+            containing loop, not just the immediate scope.
 
         Returns:
             A handle to the instruction created.

qiskit/circuit/register.py

@@ -38,7 +38,13 @@ def __get__(self, obj, objtype=None):
 
 
 class Register:
-    """Implement a generic register."""
+    """Implement a generic register.
+
+    .. note::
+        This class should not be instantiated directly. This is just a superclass
+        for :class:`~.ClassicalRegister` and :class:`~.QuantumRegister`.
+
+    """
 
     __slots__ = ["_name", "_size", "_bits", "_bit_indices", "_hash", "_repr"]