[Suggestion] Use .. plot:: directive to test code examples

[frankharkins]

Blocked by #13178

Summary

This PR switches code examples to use Matplotlib's .. plot:: directive. This runs those code examples during documentation builds, failing the build if any code examples raise an exception.

Details

We replace code blocks with the plot directive, using the :nofigs: option. Any code inside the directive is run at build time. This doesn't change the appearance of the rendered docs.

.. plot::
   :include-source:
   :nofigs:

We can also use the :context: option to share state between code examples. This is helpful to avoid duplicating imports and for interspersing code examples with prose.

.. plot::
   :include-source:
   :nofigs:
   :context: reset

   from qiskit import QuantumCircuit

.. plot::
   :include-source:
   :nofigs:
   :context:

   qc = QuantumCircuit(1)

Advantages:

• No new tools: we already use .. plot:: in lots of places across the docs
• Flexibility: Used like this, the directive just checks the code runs, and won't fail if there are meaningless deviations in the output.

Potential problems:

• The term plot may be confusing to contributors since we're not plotting anything.
• It's a bit noisy repeating the same options (:include-source:, :nofig:) everywhere.

---

Fixes Qiskit/documentation#1893

[coveralls]

Pull Request Test Coverage Report for Build 10961464387

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 28 unchanged lines in 4 files lost coverage.
• Overall coverage decreased (-0.03%) to 88.762%

---

Files with Coverage Reduction	New Missed Lines	%
qiskit/transpiler/passes/synthesis/unitary_synthesis.py	2	88.26%
qiskit/synthesis/two_qubit/xx_decompose/decomposer.py	6	90.91%
crates/qasm2/src/lex.rs	8	91.23%
crates/qasm2/src/parse.rs	12	96.69%

Totals
Change from base Build 10960489019:	-0.03%
Covered Lines:	73463
Relevant Lines:	82764

---

💛 - Coveralls

[qiskit-bot]

One or more of the following people are relevant to this code:

• @enavarro51
• @Cryoris
• @Qiskit/terra-core
• @ajavadia
• @levbishop
• @mtreinish
• @nkanazawa1989
• @t-imamichi