Improve transpiler documentation (#9087)

* Improve transpiler documentation

This commit expands the module documentation for the qiskit.transpiler
module to explain details of working with preset pass managers and how
to modify stages for custom workflows. It also updates some of the
details about the stages which were a bit stale on the exact behavior of
the transpiler.

* Apply suggestions from code review

Co-authored-by: Jake Lishman <jake@binhbar.com>

* More refactors from code review

* Update reference label for stages section

* Add section headers to scheduling stage docs

* Fix lint

* Fix typo

* Update examples to show stochastic passes

* Fix rebase typos and example issues

* Update qiskit/transpiler/__init__.py

* Apply suggestions from code review

Co-authored-by: Kevin Krsulich <kevin@krsulich.net>

* Fix trailing whitespace

* Expand init stage definition

* Apply suggestions from code review

Co-authored-by: Kevin Krsulich <kevin@krsulich.net>

* Simplify target section intro

* Highlight legacy views are for backwards compatibility

* Updating layout and routing for extra details

* Apply suggestions from code review

Co-authored-by: Kevin Hartman <kevin@hart.mn>

* Update qiskit/transpiler/preset_passmanagers/__init__.py

Co-authored-by: Kevin Hartman <kevin@hart.mn>

* More updates from code review

* Fix line length lint failure

* Apply suggestions from code review

Co-authored-by: Kevin Krsulich <kevin@krsulich.net>

* Expand sabre layout explanation

* Explain pass description in stage details header

Co-authored-by: Jake Lishman <jake@binhbar.com>
Co-authored-by: Kevin Krsulich <kevin@krsulich.net>
Co-authored-by: Kevin Hartman <kevin@hart.mn>

qiskit/transpiler/passes/scheduling/scheduling/alap.py

@@ -20,8 +20,9 @@ from qiskit.transpiler.passes.scheduling.scheduling.base_scheduler import BaseSc
 class ALAPScheduleAnalysis(BaseScheduler):
     """ALAP Scheduling pass, which schedules the **stop** time of instructions as late as possible.
 
-    See the Scheduling section in :ref:`transpiler_supplemental` for
-    the detailed behavior of the control flow operation, i.e. ``c_if``.
+    See the :ref:`scheduling_stage` section in the :mod:`qiskit.transpiler`
+    module documentation for the detailed behavior of the control flow
+    operation, i.e. ``c_if``.
     """
 
     def run(self, dag):

qiskit/transpiler/passes/scheduling/scheduling/asap.py

@@ -20,8 +20,9 @@ from qiskit.transpiler.passes.scheduling.scheduling.base_scheduler import BaseSc
 class ASAPScheduleAnalysis(BaseScheduler):
     """ASAP Scheduling pass, which schedules the start time of instructions as early as possible..
 
-    See Scheduling section in :ref:`transpiler_supplemental` for
-    the detailed behavior of the control flow operation, i.e. ``c_if``.
+    See the :ref:`scheduling_stage` section in the :mod:`qiskit.transpiler`
+    module documentation for the detailed behavior of the control flow
+    operation, i.e. ``c_if``.
     """
 
     def run(self, dag):

qiskit/transpiler/preset_passmanagers/__init__.py

@@ -17,6 +17,23 @@ Preset Passmanagers (:mod:`qiskit.transpiler.preset_passmanagers`)
 
 .. currentmodule:: qiskit.transpiler.preset_passmanagers
 
+This module contains functions for generating the preset pass managers
+for the transpiler. The preset pass managers are instances of
+:class:`~.StagedPassManager` which are used to execute the circuit
+transformations as part of Qiskit's compiler inside the
+:func:`~.transpile` function at the different optimization levels.
+The functionality here is divided into two parts, the first includes the
+functions used generate the entire pass manager which is used by
+:func:`~.transpile` (:ref:`preset_pass_manager_generators`) and the
+second includes functions which are used to build (either entirely or in
+part) the stages which the preset pass managers are composed of
+(:ref:`stage_generators`).
+
+.. _preset_pass_manager_generators:
+
+Preset Pass Manager Generation
+------------------------------
+
 .. autosummary::
    :toctree: ../stubs/
 
@@ -25,6 +42,23 @@ Preset Passmanagers (:mod:`qiskit.transpiler.preset_passmanagers`)
    level_1_pass_manager
    level_2_pass_manager
    level_3_pass_manager
+
+.. _stage_generators:
+
+Stage Generator Functions
+-------------------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ~qiskit.transpiler.preset_passmanagers.common.generate_control_flow_options_check
+   ~qiskit.transpiler.preset_passmanagers.common.generate_error_on_control_flow
+   ~qiskit.transpiler.preset_passmanagers.common.generate_unroll_3q
+   ~qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager
+   ~qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager
+   ~qiskit.transpiler.preset_passmanagers.common.generate_pre_op_passmanager
+   ~qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager
+   ~qiskit.transpiler.preset_passmanagers.common.generate_scheduling
 """
 
 from qiskit.transpiler.passmanager_config import PassManagerConfig