Document Primitives types

[yaelbh]

Summary

Closes #13969 and #14292.

SamplerPub, EstimatorPub, ParameterLike, BindingsArray, BindingsArrayLike, ObservableLike, ObservablesArray, and ObservablesArrayLike are now all imported in the Primitives __init__ file, and are present in the auto-summaries in that file.

Details and comments

I didn't add BindingArray to BindingsArrayLike and ObservablesArray to ObservablesArrayLike because these Like types already include all ArrayLike.

[qiskit-bot]

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

• @Qiskit/terra-core
• @ajavadia
• @levbishop
• @t-imamichi

[coveralls]

Pull Request Test Coverage Report for Build 15097493208

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

• 4 of 4 (100.0%) changed or added relevant lines in 1 file are covered.
• 950 unchanged lines in 27 files lost coverage.
• Overall coverage decreased (-0.4%) to 88.293%

---

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/expr.rs	1	94.23%
crates/transpiler/src/passes/elide_permutations.rs	1	97.14%
crates/transpiler/src/passes/gate_direction.rs	1	97.73%
qiskit/transpiler/passes/optimization/template_matching/template_substitution.py	1	93.54%
crates/transpiler/src/passes/split_2q_unitaries.rs	2	97.44%
qiskit/circuit/parameter.py	2	96.77%
crates/circuit/src/packed_instruction.rs	4	93.18%
crates/transpiler/src/passes/unitary_synthesis.rs	4	94.85%
qiskit/transpiler/passes/routing/star_prerouting.py	4	97.77%
crates/circuit/src/lib.rs	6	94.44%

Totals
Change from base Build 14937574463:	-0.4%
Covered Lines:	78332
Relevant Lines:	88718

---

💛 - Coveralls

[yaelbh]

@Eric-Arellano What do you suggest to do with things that look like this?
I have this problem with most of the types that I added in this PR.

[Eric-Arellano]

Hi @yaelbh , you can configure this:

qiskit/docs/conf.py

Lines 119 to 123 in 4c86574

	# Some type hints are too long to be understandable. So, we set up aliases to be used instead.
	autodoc_type_aliases = {
	"EstimatorPubLike": "EstimatorPubLike",
	"SamplerPubLike": "SamplerPubLike",
	}

[yaelbh]

@Eric-Arellano The screenshot is with EstimatorPubLike, which is already configured in conf.py.
In our code EstimatorPubLike is defined as:

EstimatorPubLike = Union[
    EstimatorPub,
    Tuple[QuantumCircuit, ObservablesArrayLike],
    Tuple[QuantumCircuit, ObservablesArrayLike, BindingsArrayLike],
    Tuple[QuantumCircuit, ObservablesArrayLike, BindingsArrayLike, Real],
]

So this is what I want the users to see in the documentation.

[Eric-Arellano]

Looking more at https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_type_aliases, I think that Sphinx option will only help when the types are used as type hints in a function.

In your PR, you are using .. autosummary with the types directly. So, the option I linked to won't help. I don't know of any way to get .. autosummary to generate what you are working for.

Rather than using autosummary, you may want to explicitly write the documentation for all of these types like ParameterLike. For example, manually write something like this:

``ParameterLike``:

   .. code-block:: python

      EstimatorPub | 
      tuple[QuantumCircuit, ObservablesArrayLike] |
      tuple[QuantumCircuit, ObservablesArrayLike, BindingsArrayLike] |
      tuple[QuantumCircuit, ObservablesArrayLike, BindingsArrayLike, Real]

[yaelbh]

Where to insert these lines? And, if this ever changes, will one have to remember to change the documentation too?

[Eric-Arellano]

Where to insert these lines?

You'll have to decide what makes the most sense. Probably in the same section headings where they are, but underneath the .. autosummary:: directive -- that means they'd be underneath the generated table.

Maybe we should talk about this briefly in the weekly dev call tomorrow?

will one have to remember to change the documentation too?

Unfortunately, yes. Matthew or Jake may have more clever ideas. I can't think of anything.

[yaelbh]

Let's do something that we're happy with for SamplerPubLike, then we can extend to other types, mainly EstimatorPubLike.

SamplerPubLike is defined in

qiskit/qiskit/primitives/containers/sampler_pub.py

Lines 172 to 193 in a18e151

	SamplerPubLike = Union[
	QuantumCircuit,
	Tuple[QuantumCircuit],
	Tuple[QuantumCircuit, BindingsArrayLike],
	Tuple[QuantumCircuit, BindingsArrayLike, Union[Integral, None]],
	]
	"""A Pub (Primitive Unified Bloc) for a Sampler.
	A fully specified sample Pub is a tuple ``(circuit, parameter_values, shots)``.
	If shots are provided this number of shots will be run with the sampler,
	if ``shots=None`` the number of run shots is determined by the sampler.
	.. note::
	A Sampler Pub can also be initialized in the following formats which
	will be converted to the full Pub tuple:
	* ``circuit``
	* ``(circuit,)``
	* ``(circuit, parameter_values)``
	"""

Current SamplerPubLike looks like this:

I'd like to:

• SamplerPubLike will have its own page. This page will contain the text that's currently displayed at the right column.
• Clicking SamplerPubLike at the left column will direct to the SamplerPubLike page.
• The right column will be much shorter and more concise: it will only contain the sentence "A Pub (Primitive Unified Bloc) for a Sampler.".
• SamplerPubLike at the left column will be in Bold and its font will be identical to the font of SamplerPub from the previous table.
• The title "Table 29 bla" will be removed.
• Column widths of the table will be identical to the previous table.

When we extend to other types, we should

• Properly define ObservablesArrayLike here (it's not a class), and attach a hyperlink to the ObservablesArrayLike page.

All of the items listed above - I would very much appreciate help to accomplish them, from folks familiar with sphinx.

Finally, note Issue #14397: it's pretty impossible to play with the documentation, when every build attempt takes 20 minutes.