Fix docs issue

Author: ElePT

qiskit/pulse/builder.py

@@ -759,6 +759,20 @@ def append_instruction(instruction: instructions.Instruction):
 def num_qubits() -> int:
     """Return number of qubits in the currently active backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+        backend = FakeOpenPulse2Q()
+        with pulse.build(backend):
+            print(pulse.num_qubits())
+
+    .. code-block:: text
+
+       2
+
     .. note:: Requires the active builder context to have a backend set.
     """
     if isinstance(active_backend(), BackendV2):
@@ -803,6 +817,20 @@ def samples_to_seconds(samples: int | np.ndarray) -> float | np.ndarray:
 def qubit_channels(qubit: int) -> set[chans.Channel]:
     """Returns the set of channels associated with a qubit.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+        backend = FakeOpenPulse2Q()
+        with pulse.build(backend):
+            print(pulse.qubit_channels(0))
+
+    .. code-block:: text
+
+       {MeasureChannel(0), ControlChannel(0), DriveChannel(0), AcquireChannel(0), ControlChannel(1)}
+
     .. note:: Requires the active builder context to have a backend set.
 
     .. note:: A channel may still be associated with another qubit in this list
@@ -1168,6 +1196,33 @@ def frequency_offset(
 ) -> Generator[None, None, None]:
     """Shift the frequency of inputs channels on entry into context and undo on exit.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+        d0 = pulse.DriveChannel(0)
+
+        with pulse.build(backend) as pulse_prog:
+            # shift frequency by 1GHz
+            with pulse.frequency_offset(1e9, d0):
+                pulse.play(pulse.Constant(10, 1.0), d0)
+
+        assert len(pulse_prog.instructions) == 3
+
+        with pulse.build(backend) as pulse_prog:
+            # Shift frequency by 1GHz.
+            # Undo accumulated phase in the shifted frequency frame
+            # when exiting the context.
+            with pulse.frequency_offset(1e9, d0, compensate_phase=True):
+                pulse.play(pulse.Constant(10, 1.0), d0)
+
+        assert len(pulse_prog.instructions) == 4
+
+
     Args:
         frequency: Amount of frequency offset in Hz.
         channels: Channels to offset frequency of.
@@ -1205,6 +1260,18 @@ def frequency_offset(
 def drive_channel(qubit: int) -> chans.DriveChannel:
     """Return ``DriveChannel`` for ``qubit`` on the active builder backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.drive_channel(0) == pulse.DriveChannel(0)
+
     .. note:: Requires the active builder context to have a backend set.
     """
     # backendV2
@@ -1217,6 +1284,18 @@ def drive_channel(qubit: int) -> chans.DriveChannel:
 def measure_channel(qubit: int) -> chans.MeasureChannel:
     """Return ``MeasureChannel`` for ``qubit`` on the active builder backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.measure_channel(0) == pulse.MeasureChannel(0)
+
     .. note:: Requires the active builder context to have a backend set.
     """
     # backendV2
@@ -1229,6 +1308,18 @@ def measure_channel(qubit: int) -> chans.MeasureChannel:
 def acquire_channel(qubit: int) -> chans.AcquireChannel:
     """Return ``AcquireChannel`` for ``qubit`` on the active builder backend.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.acquire_channel(0) == pulse.AcquireChannel(0)
+
     .. note:: Requires the active builder context to have a backend set.
     """
     # backendV2
@@ -1244,6 +1335,18 @@ def control_channels(*qubits: Iterable[int]) -> list[chans.ControlChannel]:
     Return the secondary drive channel for the given qubit -- typically
     utilized for controlling multi-qubit interactions.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend):
+            assert pulse.control_channels(0, 1) == [pulse.ControlChannel(0)]
+
     .. note:: Requires the active builder context to have a backend set.
 
     Args:
@@ -1736,10 +1839,7 @@ def barrier(*channels_or_qubits: chans.Channel | int, name: str | None = None):
     the barrier. Consider the case where we want to enforce that one pulse
     happens after another on separate channels, this can be done with:
 
-    .. plot::
-       :include-source:
-       :nofigs:
-       :context: reset
+    .. code-block:: python
 
         from qiskit import pulse
         from qiskit.providers.fake_provider import FakeOpenPulse2Q
@@ -1756,10 +1856,7 @@ def barrier(*channels_or_qubits: chans.Channel | int, name: str | None = None):
 
     Of course this could have been accomplished with:
 
-    .. plot::
-       :include-source:
-       :nofigs:
-       :context:
+    .. code-block:: python
 
         from qiskit.pulse import transforms
 
@@ -1821,6 +1918,29 @@ def macro(func: Callable):
     behave as if the function code was embedded inline in the parent builder context
     after parameter substitution.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        @pulse.macro
+        def measure(qubit: int):
+            pulse.play(pulse.GaussianSquare(16384, 256, 15872), pulse.measure_channel(qubit))
+            mem_slot = pulse.MemorySlot(qubit)
+            pulse.acquire(16384, pulse.acquire_channel(qubit), mem_slot)
+
+            return mem_slot
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend=backend) as sched:
+            mem_slot = measure(0)
+            print(f"Qubit measured into {mem_slot}")
+
+        sched.draw()
+
     Args:
         func: The Python function to enable as a builder macro. There are no
             requirements on the signature of the function, any calls to pulse
@@ -1942,6 +2062,19 @@ def measure_all() -> list[chans.MemorySlot]:
     same time. This is useful for handling device ``meas_map`` and single
     measurement constraints.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse2Q
+
+        backend = FakeOpenPulse2Q()
+
+        with pulse.build(backend) as pulse_prog:
+            # Measure all qubits and return associated registers.
+            regs = pulse.measure_all()
+
     .. note::
         Requires the active builder context to have a backend set.
 
@@ -1970,6 +2103,19 @@ def delay_qubits(duration: int, *qubits: int):
     r"""Insert delays on all the :class:`channels.Channel`\s that correspond
     to the input ``qubits`` at the same time.
 
+    Examples:
+
+    .. code-block:: python
+
+        from qiskit import pulse
+        from qiskit.providers.fake_provider import FakeOpenPulse3Q
+
+        backend = FakeOpenPulse3Q()
+
+        with pulse.build(backend) as pulse_prog:
+            # Delay for 100 cycles on qubits 0, 1 and 2.
+            regs = pulse.delay_qubits(100, 0, 1, 2)
+
     .. note:: Requires the active builder context to have a backend set.
 
     Args: