API Reference Guidelines

Note

We are mainly using jupyter-execute directive for including code examples. We will investigate using doctest to replace jupyter-execute in the future wherever it’s possible to reduce doc building process complexity. See qiskit-terra#7661 for discussions.

1. Show a decent amount of arguments / options

Focus on the arguments that make bigger differences. If there are multiple arguments with similar functionality, show only the ones with significant differences. For example, if you are using plot_histogram and want to show different options of the sort argument, don’t pick two that mostly do the same like value and value_desc, pick one of them to show you can sort by probability and a completely different one like hamming.

To minimize duplication of content, put common things in the module level api page instead of class, method, function level api page. For example, qiskit-terra#8569 added common usage explanations and code examples to qiskit.visualization module level API page.

2. Be reasonable with the amount of code examples/cells

If there are more than 4 arguments that make significant changes, it can be better to distribute them evenly between 2 examples. That way you avoid having an overloaded example and a user can see how some of the default values work.

Avoid adding more than 3 code examples. Too many examples make the page noisy. If you want to demonstrate more functionalities, please consider writing a dedicated how-to guide.

3. Don’t over complicate nor oversimplify the steps to get the input arguments

The priority should always be showing the object/function itself, not the many ways of obtaining the input. So try to stick to the simplest way to show the desired functionality.

If a more complicated input is useful to show some functionality, like creating a state with many different amplitudes to show the different square sizes for a hinton diagram, do it but in the simplest way possible (the fewest possible gates, use relatively common gates, avoid extra imports like numpy).

On the other side, make sure you are showing the full functionality.

4. Import only what’s strictly needed when needed

If you have more than one example, don’t repeat the imports from the former examples. Only add the ones that don’t appear there. That’s because these cells are all in one Jupyter kernel session. It will make code examples look cleaner. And if users want to use only one of the examples, they just need to copy all the imports from previous cells.

5. Make all the different examples self-contained (except for the imports)

Don’t reuse variables like backends even if they are the same in more than one example. That way a user can directly copy and paste the desired example without having to look carefully into the variables of the rest.