Increase documentation of built-in transpiler plugins

This overhauls how the `qiskit.transpiler` documentation talks about the
transpiler plugins.  All of the built-in plugins now have a decent
amount of overview documentation, and the requirements and expectations
for each stage of the preset pipelines is explained in more detail.

This form of the documentation makes the distinction between "a
compilation routine in general" and "Qiskit's specific choice of default
pipeline" clearer, to avoid confusion for advanced users.

Much of the guide-level explanations of the different preset pipeline
stages moved to https://docs.quantum.ibm.com some time ago, so this PR
removes those, in favour of focussing on the actual API, and inserts
links to learn more about the principles elsewhere.

The guide-level explanation of scheduling is left in-place for now,
because the content on the other parts of the IBM documentation isn't as
complete for that.

qiskit/transpiler/layout.py

@@ -445,10 +445,10 @@ class TranspileLayout:
 
     The :mod:`~qiskit.transpiler` is unitary-preserving up to the "initial layout"
     and "final layout" permutations. The initial layout permutation is caused by
-    setting and applying the initial layout during the :ref:`layout_stage`.
+    setting and applying the initial layout during the :ref:`transpiler-preset-stage-layout`.
     The final layout permutation is caused by :class:`~.SwapGate` insertion during
-    the :ref:`routing_stage`. This class provides an interface to reason about these
-    permutations using a variety of helper methods.
+    the :ref:`transpiler-preset-stage-routing`. This class provides an interface to reason about
+    these permutations using a variety of helper methods.
 
     During the layout stage, the transpiler can potentially remap the order of the
     qubits in the circuit as it fits the circuit to the target backend. For example,
@@ -521,7 +521,7 @@ class TranspileLayout:
     state from the transpiler. They are defined as:
 
       * :attr:`initial_layout` - This attribute is used to model the
-        permutation caused by the :ref:`layout_stage`. It is a
+        permutation caused by the :ref:`transpiler-preset-stage-layout`. It is a
         :class:`~.Layout` object that maps the input :class:`~.QuantumCircuit`\s
         :class:`~.circuit.Qubit` objects to the position in the output
         :class:`.QuantumCircuit.qubits` list.
@@ -533,12 +533,12 @@ class TranspileLayout:
         is needed when computing the permutation of the :class:`Operator` of
         the circuit (and used by :meth:`.Operator.from_circuit`).
       * :attr:`final_layout` - This attribute is used to model the
-        permutation caused by the :ref:`routing_stage`. It is a
+        permutation caused by the :ref:`transpiler-preset-stage-routing`. It is a
         :class:`~.Layout` object that maps the output circuit's qubits from
         :class:`.QuantumCircuit.qubits` in the output circuit to their final
         positions after routing. Importantly, this only represents the
         permutation caused by inserting :class:`~.SwapGate`\s into
-        the :class:`~.QuantumCircuit` during the :ref:`routing_stage`.
+        the :class:`~.QuantumCircuit` during the :ref:`transpiler-preset-stage-routing`.
         It is **not** a mapping from the original input circuit's position
         to the final position at the end of the transpiled circuit.
         If you need this, you can use the :meth:`.final_index_layout` to generate this.

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

@@ -20,7 +20,7 @@
 class ALAPScheduleAnalysis(BaseScheduler):
     """ALAP Scheduling pass, which schedules the **stop** time of instructions as late as possible.
 
-    See the :ref:`scheduling_stage` section in the :mod:`qiskit.transpiler`
+    See the :ref:`transpiler-scheduling-description` section in the :mod:`qiskit.transpiler`
     module documentation for the detailed behavior of the control flow
     operation, i.e. ``c_if``.
     """

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

@@ -20,7 +20,7 @@
 class ASAPScheduleAnalysis(BaseScheduler):
     """ASAP Scheduling pass, which schedules the start time of instructions as early as possible.
 
-    See the :ref:`scheduling_stage` section in the :mod:`qiskit.transpiler`
+    See the :ref:`transpiler-scheduling-description` section in the :mod:`qiskit.transpiler`
     module documentation for the detailed behavior of the control flow
     operation, i.e. ``c_if``.
     """

qiskit/transpiler/preset_passmanagers/__init__.py

@@ -32,21 +32,23 @@
 
 .. _preset_pass_manager_generators:
 
-Preset Pass Manager Generation
-------------------------------
+Low-level Preset Pass Manager Generation
+----------------------------------------
 
-.. autofunction:: generate_preset_pass_manager
 .. autofunction:: level_0_pass_manager
 .. autofunction:: level_1_pass_manager
 .. autofunction:: level_2_pass_manager
 .. autofunction:: level_3_pass_manager
 
+..
+    `generate_preset_pass_manager` is not documented here because it's documented to be at the root
+    of `qiskit.transpiler`.
+
 .. _stage_generators:
 
 Stage Generator Functions
 -------------------------
 
-.. currentmodule:: qiskit.transpiler.preset_passmanagers.common
 .. autofunction:: generate_control_flow_options_check
 .. autofunction:: generate_error_on_control_flow
 .. autofunction:: generate_unroll_3q
@@ -55,8 +57,18 @@
 .. autofunction:: generate_pre_op_passmanager
 .. autofunction:: generate_translation_passmanager
 .. autofunction:: generate_scheduling
-.. currentmodule:: qiskit.transpiler.preset_passmanagers
 """
+
+from .common import (
+    generate_control_flow_options_check,
+    generate_error_on_control_flow,
+    generate_unroll_3q,
+    generate_embed_passmanager,
+    generate_routing_passmanager,
+    generate_pre_op_passmanager,
+    generate_translation_passmanager,
+    generate_scheduling,
+)
 from .generate_preset_pass_manager import generate_preset_pass_manager
 from .level0 import level_0_pass_manager
 from .level1 import level_1_pass_manager
@@ -70,4 +82,12 @@
     "level_2_pass_manager",
     "level_3_pass_manager",
     "generate_preset_pass_manager",
+    "generate_control_flow_options_check",
+    "generate_error_on_control_flow",
+    "generate_unroll_3q",
+    "generate_embed_passmanager",
+    "generate_routing_passmanager",
+    "generate_pre_op_passmanager",
+    "generate_translation_passmanager",
+    "generate_scheduling",
 ]

qiskit/transpiler/preset_passmanagers/plugin.py

@@ -11,6 +11,8 @@
 # that they have been altered from the originals.
 
 """
+.. _transpiler-preset-stage-plugins:
+
 =======================================================================================
 Transpiler Stage Plugin Interface (:mod:`qiskit.transpiler.preset_passmanagers.plugin`)
 =======================================================================================
@@ -36,65 +38,54 @@
 =============
 
 Currently, there are 6 stages in the preset pass managers, all of which actively
-load external plugins via corresponding entry points.
+load external plugins via corresponding entry points.  The table below gives a quick summary of each
+stage.  For more details on the description and expectations of each stage, follow the link in the
+stages' names to the full documentation.
 
 .. list-table:: Stages
    :header-rows: 1
 
    * - Stage Name
      - Entry Point
      - Reserved Names
-     - Description and expectations
-   * - ``init``
+     - Summary
+
+   * - :ref:`init <transpiler-preset-stage-init>`
      - ``qiskit.transpiler.init``
      - ``default``
-     - This stage runs first and is typically used for any initial logical optimization. Because most
-       layout and routing algorithms are only designed to work with 1 and 2 qubit gates, this stage
-       is also used to translate any gates that operate on more than 2 qubits into gates that only
-       operate on 1 or 2 qubits.
-   * - ``layout``
+     - High-level, logical optimizations on abstract circuits, and reduction of multi-qubit
+       operations to 1- and 2-qubit operations.
+
+   * - :ref:`layout <transpiler-preset-stage-layout>`
      - ``qiskit.transpiler.layout``
      - ``trivial``, ``dense``, ``sabre``, ``default``
-     - The output from this stage is expected to have the ``layout`` property
-       set field set with a :class:`~.Layout` object. Additionally, the circuit is
-       typically expected to be embedded so that it is expanded to include all
-       qubits and the :class:`~.ApplyLayout` pass is expected to be run to apply the
-       layout. The embedding of the :class:`~.Layout` can be generated with
-       :func:`~.generate_embed_passmanager`.
-   * - ``routing``
+     - Choose an initial mapping of virtual qubits to physical qubits, including expansion of the
+       circuit to include explicit ancillas.  This stage is sometimes combined with ``routing``.
+
+   * - :ref:`routing <transpiler-preset-stage-routing>`
      - ``qiskit.transpiler.routing``
      - ``basic``, ``stochastic``, ``lookahead``, ``sabre``
-     - The output from this stage is expected to have the circuit match the
-       connectivity constraints of the target backend. This does not necessarily
-       need to match the directionality of the edges in the target as a later
-       stage typically will adjust directional gates to match that constraint
-       (but there is no penalty for doing that in the ``routing`` stage). The output
-       of this stage is also expected to have the ``final_layout`` property set field
-       set with a :class:`~.Layout` object that maps the :class:`.Qubit` to the
-       output final position of that qubit in the circuit. If there is an
-       existing ``final_layout`` entry in the property set (such as might be set
-       by an optimization pass that introduces a permutation) it is expected
-       that the final layout will be the composition of the two layouts (this
-       can be computed using :meth:`.DAGCircuit.compose`, for example:
-       ``second_final_layout.compose(first_final_layout, dag.qubits)``).
-   * - ``translation``
+     - Insert gates into the circuit to ensure it matches the connectivity constraints of the
+       :class:`.Target`.  The inserted gates do not need to be in the target ISA yet, so are often
+       just output as ``swap`` instructions.  This stage is sometimes subsumed by ``layout``.
+
+   * - :ref:`translation <transpiler-preset-stage-translation>`
      - ``qiskit.transpiler.translation``
      - ``translator``, ``synthesis``, ``unroller``
-     - The output of this stage is expected to have every operation be a native
-        instruction on the target backend.
-   * - ``optimization``
+     - Rewrite all gates outside the target ISA to use only gates within the ISA.
+
+   * - :ref:`optimization <transpiler-preset-stage-optimization>`
      - ``qiskit.transpiler.optimization``
      - ``default``
-     - This stage is expected to perform optimization and simplification.
-       The constraints from earlier stages still apply to the output of this
-       stage. After the ``optimization`` stage is run we expect the circuit
-       to still be executable on the target.
-   * - ``scheduling``
+     - Low-level, physical-circuit-aware optimizations.  Unlike ``init``, the ``optimization`` stage
+       acts at the level of a physical circuit.
+
+   * - :ref:`scheduling <transpiler-preset-stage-scheduling>`
      - ``qiskit.transpiler.scheduling``
      - ``alap``, ``asap``, ``default``
-     - This is the last stage run and it is expected to output a scheduled
-       circuit such that all idle periods in the circuit are marked by explicit
-       :class:`~qiskit.circuit.Delay` instructions.
+     - Insert :class:`~.circuit.Delay` instructions to make the wall-clock timing of the circuit
+       fully explicit.
+
 
 Writing Plugins
 ===============