Reorganize transpiler modules in API docs (Qiskit#1645)

Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime.

## Reduces `transpiler` modules

Before:

| module | status |
| --- | --- |
| qiskit.transpiler | only links to `passes` |
| qiskit.transpiler.passes | only links to `basis` and `scheduling` |
| qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't |
| qiskit.transpiler.passes.scheduling | useful |

Now:

| module | status |
| --- | --- |
| qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` |
| qiskit.transpiler.passes.scheduling | useful |

This saves the user clicks. Now each page is useful enough to stand on its own.

This is what the index page now looks like:

<img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b">

This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again.

This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future.

## Improves header hierarchy

### Options

Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers).

### `qiskit_ibm_runtime.transpiler.passes.scheduling`

This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels.

## Removes unused docstrings

The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.

docs/apidocs/transpiler.rst

@@ -1,4 +1,4 @@
-.. automodule:: qiskit_ibm_runtime.transpiler
+.. automodule:: qiskit_ibm_runtime.transpiler.passes
    :no-members:
    :no-inherited-members:
    :no-special-members:

qiskit_ibm_runtime/options/__init__.py

@@ -19,7 +19,8 @@
 
 Options that can be passed to the primitives.
 
-**V2 Primitives**
+V2 Primitives
+=============
 
 ``SamplerV2`` and ``EstimatorV2`` each have their own options. You can use the
 ``options`` attribute to set the options. For example::
@@ -50,7 +51,8 @@
    for the most up-to-date default values.
 
 
-**V1 Primitives**
+V1 Primitives
+=============
 
 The :class:`Options` class encapsulates all the options you can specify
 when invoking a V1 primitive. It includes frequently used options,
@@ -72,7 +74,8 @@
 
 
 Classes
-==========================
+=======
+
 .. autosummary::
    :toctree: ../stubs/
 

qiskit_ibm_runtime/transpiler/__init__.py

@@ -10,22 +10,4 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-====================================================================
-IBM Backend Transpiler Tools (:mod:`qiskit_ibm_runtime.transpiler`)
-====================================================================
-
-A collection of transpiler tools for working with IBM Quantum's
-next-generation backends that support advanced "dynamic circuit"
-capabilities. Ie., circuits with support for classical
-compute and control-flow/feedback based off of measurement results.
-
-Transpiler Passes
-==================
-
-.. autosummary::
-    :toctree: ../stubs/
-
-    passes
-
-"""
+"""Tools for transpilation."""

qiskit_ibm_runtime/transpiler/passes/__init__.py

@@ -12,20 +12,21 @@
 
 """
 ================================================================
-Transpiler Passes (:mod:`qiskit_ibm_runtime.transpiler.passes`)
+Transpiler passes (:mod:`qiskit_ibm_runtime.transpiler.passes`)
 ================================================================
 
 .. currentmodule:: qiskit_ibm_runtime.transpiler.passes
 
-A collection of transpiler passes for IBM backends.
+A collection of transpiler passes for IBM backends. Refer to
+https://docs.quantum.ibm.com/transpile to learn more about
+transpilation and passes.
 
 .. autosummary::
    :toctree: ../stubs/
 
-   basis
+   ConvertIdToDelay
    scheduling
 
-
 """
 
 from .basis import ConvertIdToDelay

qiskit_ibm_runtime/transpiler/passes/basis/__init__.py

@@ -10,14 +10,6 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-==========================================================
-Basis (:mod:`qiskit_ibm_runtime.transpiler.passes.basis`)
-==========================================================
-
-.. currentmodule:: qiskit_ibm_runtime.transpiler.passes.basis
-
-Passes to layout circuits to IBM backend's instruction sets.
-"""
+"""Passes to layout circuits to IBM backend's instruction sets."""
 
 from .convert_id_to_delay import ConvertIdToDelay

qiskit_ibm_runtime/transpiler/passes/scheduling/__init__.py

@@ -29,6 +29,21 @@
     :func:`~qiskit.compiler.transpile` or
     :func:`~qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager`.
 
+Classes
+=======
+.. autosummary::
+   :toctree: ../stubs/
+
+    BlockBasePadder
+    ALAPScheduleAnalysis
+    ASAPScheduleAnalysis
+    DynamicCircuitInstructionDurations
+    PadDelay
+    PadDynamicalDecoupling
+
+Example usage
+=============
+
 Below we demonstrate how to schedule and pad a teleportation circuit with delays
 for a dynamic circuit backend's execution model:
 
@@ -114,7 +129,7 @@
 
 
 Scheduling old format ``c_if`` conditioned gates
-------------------------------------------------
+================================================
 
 Scheduling with old format ``c_if`` conditioned gates is not supported.
 
@@ -171,7 +186,7 @@
 
 
 Exploiting IBM backend's local parallel "fast-path"
----------------------------------------------------
+===================================================
 
 IBM quantum hardware supports a localized "fast-path" which enables a block of gates
 applied to a *single qubit* that are conditional on an immediately predecessor measurement
@@ -375,18 +390,6 @@
 
         qc.draw(output="mpl", style="iqp")
 
-
-Scheduling & Dynamical Decoupling
-=================================
-.. autosummary::
-   :toctree: ../stubs/
-
-    BlockBasePadder
-    ALAPScheduleAnalysis
-    ASAPScheduleAnalysis
-    DynamicCircuitInstructionDurations
-    PadDelay
-    PadDynamicalDecoupling
 """
 
 from .block_base_padder import BlockBasePadder

qiskit_ibm_runtime/utils/__init__.py

@@ -10,30 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-==============================================================================
-Utilities (:mod:`qiskit_ibm_runtime.utils`)
-==============================================================================
-
-.. currentmodule:: qiskit_ibm_runtime.utils
-
-Utility functions related to the IBM Runtime Services.
-
-Conversion
-==========
-.. autosummary::
-    :toctree: ../stubs/
-
-    seconds_to_duration
-    utc_to_local
-
-Misc Functions
-==============
-.. autosummary::
-    :toctree: ../stubs/
-
-    to_python_identifier
-"""
+"""Internal utilities."""
 
 from .converters import (
     utc_to_local,