Improve header hierarchy for API module pages (#12325) (#12350)

* Improve header hierarchy for API module pages

* Tweaks

* Review feedback

(cherry picked from commit f39c907)

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

qiskit/assembler/__init__.py

@@ -17,23 +17,18 @@
 
 .. currentmodule:: qiskit.assembler
 
-Circuit Assembler
-=================
+Functions
+=========
 
-.. autofunction:: assemble_circuits
 
-Schedule Assembler
-==================
+.. autofunction:: assemble_circuits
 
 .. autofunction:: assemble_schedules
 
-Disassembler
-============
-
 .. autofunction:: disassemble
 
-RunConfig
-=========
+Classes
+=======
 
 .. autosummary::
    :toctree: ../stubs/

qiskit/circuit/__init__.py

@@ -203,8 +203,8 @@
 
 .. _circuit-module-api:
 
-API overview of :mod:`qiskit.circuit`
-=====================================
+API overview of qiskit.circuit
+==============================
 
 All objects here are described in more detail, and in their greater context in the following
 sections.  This section provides an overview of the API elements documented here.

qiskit/circuit/classical/types/__init__.py

@@ -47,13 +47,14 @@
 Working with types
 ==================
 
-There are some functions on these types exposed here as well.  These are mostly expected to be used
-only in manipulations of the expression tree; users who are building expressions using the
+There are some additional functions on these types documented in the subsequent sections. 
+These are mostly expected to be used only in manipulations of the expression tree;
+users who are building expressions using the
 :ref:`user-facing construction interface <circuit-classical-expressions-expr-construction>` should
 not need to use these.
 
 Partial ordering of types
--------------------------
+=========================
 
 The type system is equipped with a partial ordering, where :math:`a < b` is interpreted as
 ":math:`a` is a strict subtype of :math:`b`".  Note that the partial ordering is a subset of the
@@ -78,7 +79,7 @@
 
 
 Casting between types
----------------------
+=====================
 
 It is common to need to cast values of one type to another type.  The casting rules for this are
 embedded into the :mod:`types` module.  You can query the casting kinds using :func:`cast_kind`:

qiskit/circuit/classicalfunction/__init__.py

@@ -81,6 +81,7 @@ def grover_oracle(a: Int1, b: Int1, c: Int1, d: Int1) -> Int1:
 
 Decorator for a classical function that returns a `ClassicalFunction` object.
 
+.. autofunction:: classical_function
 
 ClassicalFunction
 -----------------

qiskit/circuit/library/__init__.py

@@ -129,35 +129,19 @@
 Standard Directives
 ===================
 
-..
-    This summary table deliberately does not generate toctree entries; these directives are "owned"
-    by ``qiskit.circuit``.
-
 Directives are operations to the quantum stack that are meant to be interpreted by the backend or
 the transpiler. In general, the transpiler or backend might optionally ignore them if there is no
 implementation for them.
 
-..
-    This summary table deliberately does not generate toctree entries; these directives are "owned"
-    by ``qiskit.circuit``.
-
-.. autosummary::
-
-   Barrier
+* :class:`qiskit.circuit.Barrier`
 
 Standard Operations
 ===================
 
 Operations are non-reversible changes in the quantum state of the circuit.
 
-..
-    This summary table deliberately does not generate toctree entries; these directives are "owned"
-    by ``qiskit.circuit``.
-
-.. autosummary::
-
-   Measure
-   Reset
+* :class:`qiskit.circuit.Measure`
+* :class:`qiskit.circuit.Reset`
 
 Generalized Gates
 =================

qiskit/converters/__init__.py

@@ -17,12 +17,27 @@
 
 .. currentmodule:: qiskit.converters
 
-.. autofunction:: circuit_to_dag
-.. autofunction:: dag_to_circuit
+QuantumCircuit -> circuit components
+====================================
+
 .. autofunction:: circuit_to_instruction
 .. autofunction:: circuit_to_gate
+
+QuantumCircuit <-> DagCircuit 
+=============================
+
+.. autofunction:: circuit_to_dag
+.. autofunction:: dag_to_circuit
+
+QuantumCircuit <-> DagDependency 
+================================
+
 .. autofunction:: dagdependency_to_circuit
 .. autofunction:: circuit_to_dagdependency
+
+DagCircuit <-> DagDependency 
+============================
+
 .. autofunction:: dag_to_dagdependency
 .. autofunction:: dagdependency_to_dag
 """

qiskit/providers/__init__.py

@@ -131,7 +131,6 @@
 .. autoexception:: JobTimeoutError
 .. autoexception:: BackendConfigurationError
 
-=====================
 Writing a New Backend
 =====================
 
@@ -164,7 +163,7 @@
 `qiskit-aqt-provider <https://github.com/Qiskit-Partners/qiskit-aqt-provider>`__
 
 Provider
-========
+--------
 
 A provider class serves a single purpose: to get backend objects that enable
 executing circuits on a device or simulator. The expectation is that any
@@ -195,7 +194,7 @@ def backends(self, name=None, **kwargs):
 method matches the required interface. The rest is up to the specific provider on how to implement.
 
 Backend
-=======
+-------
 
 The backend classes are the core to the provider. These classes are what
 provide the interface between Qiskit and the hardware or simulator that will
@@ -276,8 +275,8 @@ def run(circuits, **kwargs):
             return MyJob(self. job_handle, job_json, circuit)
 
 
-Transpiler Interface
---------------------
+Backend's Transpiler Interface
+------------------------------
 
 The key piece of the :class:`~qiskit.providers.Backend` object is how it describes itself to the
 compiler. This is handled with the :class:`~qiskit.transpiler.Target` class which defines
@@ -453,8 +452,8 @@ def get_translation_stage_plugin(self):
 efficient output on ``Mybackend`` the transpiler will be able to perform these
 custom steps without any manual user input.
 
-Run Method
-----------
+Backend.run Method
+--------------------
 
 Of key importance is the :meth:`~qiskit.providers.BackendV2.run` method, which
 is used to actually submit circuits to a device or simulator. The run method
@@ -484,8 +483,8 @@ def run(self, circuits. **kwargs):
         job_handle = submit_to_backend(job_jsonb)
         return MyJob(self. job_handle, job_json, circuit)
 
-Options
--------
+Backend Options
+---------------
 
 There are often several options for a backend that control how a circuit is run.
 The typical example of this is something like the number of ``shots`` which is
@@ -515,7 +514,7 @@ def _default_options(cls):
 
 
 Job
-===
+---
 
 The output from the :obj:`~qiskit.providers.BackendV2.run` method is a :class:`~qiskit.providers.JobV1`
 object. Each provider is expected to implement a custom job subclass that
@@ -612,7 +611,7 @@ def status(self):
             return JobStatus.DONE
 
 Primitives
-==========
+----------
 
 While not directly part of the provider interface, the :mod:`qiskit.primitives`
 module is tightly coupled with providers. Specifically the primitive
@@ -640,12 +639,8 @@ def status(self):
 :class:`~.Estimator`, :class:`~.BackendSampler`, and :class:`~.BackendEstimator`
 can serve as references/models on how to implement these as well.
 
-======================================
-Migrating between Backend API Versions
-======================================
-
-BackendV1 -> BackendV2
-======================
+Migrating from BackendV1 to BackendV2
+=====================================
 
 The :obj:`~BackendV2` class re-defined user access for most properties of a
 backend to make them work with native Qiskit data structures and have flatter

qiskit/providers/basic_provider/__init__.py

@@ -27,36 +27,15 @@
    backend = BasicProvider().get_backend('basic_simulator')
 
 
-Simulators
-==========
+Classes
+=======
 
 .. autosummary::
    :toctree: ../stubs/
 
    BasicSimulator
-
-Provider
-========
-
-.. autosummary::
-   :toctree: ../stubs/
-
    BasicProvider
-
-Job Class
-=========
-
-.. autosummary::
-   :toctree: ../stubs/
-
    BasicProviderJob
-
-Exceptions
-==========
-
-.. autosummary::
-   :toctree: ../stubs/
-
    BasicProviderError
 """
 

qiskit/providers/fake_provider/__init__.py

@@ -24,7 +24,7 @@
 useful for testing the transpiler and other backend-facing functionality.
 
 Example Usage
-=============
+-------------
 
 Here is an example of using a simulated backend for transpilation and running.
 

qiskit/providers/models/__init__.py

@@ -19,8 +19,8 @@
 
 Qiskit schema-conformant objects used by the backends and providers.
 
-Backend Objects
-===============
+Classes
+=======
 
 .. autosummary::
    :toctree: ../stubs/