Write module-level `qiskit.circuit` documentation

[jakelishman]

Summary

I was pretty surprised to see that we had very little written for our principal module, and the first entry in our API docs.

This is a totally new set of documentation for the qiskit.circuit module, including discussion of what circuits are, what they represent in Qiskit, how all the different data elements fit together, and where to go for more information on things.

This commit is intended to be followed by a later one that does a similar rewrite for the whole QuantumCircuit class, including structuring its references to all its attributes and methods, and adding a holistic view of how the methods fit together. This is why there are some (hidden to Sphinx) TODO comments scattered throughout this documentation.

Details and comments

I consider this PR to be about half the work I was intending to do; the other is to do a similar thing to this to the QuantumCircuit page itself. Some notable concepts I was intending to include in that were:

• actual grouping structure to how the methods are presented
• append, _append and compose and their differences
• the control-flow builder interfaces
• what layout is and when it's populated

I tweaked some of the documented classes here to remove redundant or useless information, but I didn't attempt any complete rewrites of every single object in qiskit.circuit, so there's likely still many places that could benefit from short examples. I also think there's places where we might want to link to "tutorial-like" documentation elsewhere on docs.quantum.ibm.com; this is API-level documentation and primarily concerns how to interact with the objects at a fairly local level, and how their APIs fit together to build up the API of the whole circuit module.

As a minor code change, this formally documents the SessionEquivalenceLibrary module attribute and makes it available from the qiskit.circuit root.

---

Here's a link to the Azure run for the first commit, from which you can hopefully find the docs build as the "1 artifact" under the "Preliminary tests" stage. Admittedly it just uses Sphinx's built-in Alabaster theme, so isn't really representative of what it would look like on IQP - it's just what would happened with "unthemed" Sphinx. (Weirdly, the docs artefact seems to overlap the left sidebar and the content for me, which it didn't do from a local build.)

[qiskit-bot]

One or more of the the following people are requested to review this:

• @Cryoris
• @Qiskit/terra-core
• @ajavadia

[coveralls]

Pull Request Test Coverage Report for Build 8164587467

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 13 of 13 (100.0%) changed or added relevant lines in 10 files are covered.
• 117 unchanged lines in 10 files lost coverage.
• Overall coverage decreased (-0.03%) to 89.281%

---

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/expr.rs	1	93.81%
qiskit/circuit/instruction.py	2	95.91%
crates/accelerate/src/two_qubit_decompose.rs	7	93.2%
crates/qasm2/src/lex.rs	7	90.68%
qiskit/circuit/library/standard_gates/multi_control_rotation_gates.py	10	92.9%
qiskit/transpiler/preset_passmanagers/common.py	11	89.62%
crates/qasm2/src/parse.rs	12	96.23%
crates/accelerate/src/pauli_exp_val.rs	14	89.03%
qiskit/providers/backend_compat.py	15	85.71%
qiskit/qpy/binary_io/circuits.py	38	91.55%
<!--	Total:	117

Totals
Change from base Build 8052013397:	-0.03%
Covered Lines:	59107
Relevant Lines:	66203

---

💛 - Coveralls

[Eric-Arellano]

See https://github.com/Qiskit/documentation/pull/929 for a preview of this in IQP and instructions on how to run it locally and also regenerate the docs.

[sbrandhsn]

Thanks for writing this up! I learned a lot while reading this! :-) I will go over your comments tomorrow and sorry for submitting individual comments instead of one batch of comments with one code review. :s

[jakelishman]

At the request of the docs team, I've temporarily moved most of the inline class documentation into autosummary tables in a564e59acd8. Once the IBM docs platform can support them a little better, we can evaluate whether it's better to have them inline (imo, for most classes it's a "yes", but that's open for discussion).

[jakelishman]

Sebastian: I've responded to all your comments, either with changes or follow-ups. I marked quite a lot of conversations as "resolved" for the purposes of making open discussions easier to scan, but feel free to unresolve any you think I didn't adequately address.

[sbrandhsn]

Thanks @jakelishman! Let's discuss the remaining bits in the qiskit-dev meeting and then I think the circuit documentation is good to go. Thanks for writing this up! :-)

[jakelishman]

Following discussion in the dev meeting today, I've switched all "near time" and "runtime" terminology to "real time" in dd78e25a6c8.