Cleanup structure of option documentation

[nkanazawa1989]

Summary

close #1076

Details and comments

Note that from end-user perspective subclass option and parent class option don't matter because one gets mixture of all inherited and subclass options when calling analysis.options for example.

[nkanazawa1989]

Now option documentation looks like this.

[coruscating]

This is a great improvement! And thanks for updating docstrings, this also closes #1007.

[coruscating]

I don't think the parentheses are necessary. What do you think about f"Options {description} :class:`.{mro_cls.__name__}`:" instead?

[nkanazawa1989]

I was also thinking of this. However, the structure of sections, i.e. Experiment Options, Transpiler Options, Run Options, became difficult to understand because these section tiles (.. rubric::) and added plain text are the same font size. Do you know better Sphinx directive for these section titles?

[coruscating]

Hmm, what about changing the .. rubric:: section titles to headings, and changing this line to .. rubric::? Then it would look something like this:

I think it's nice to promote the section titles to headings so they can be linked to easily, and in theory the user can also quickly jump to a section using the sidebar.

Also, I wonder if we should move the default option value into the option description and remove the dropdown, would that look cleaner? Something like,

• max_circuits (Optional[int], default: None) – The maximum number of circuits per job when running an experiment on a backend.

[nkanazawa1989]

That's good idea. Default value can be sometime very long (e.g. ndarray of length 100 to represent scanned value), sometime without pretty printing, and such value make documentation unnecessary long.

[nkanazawa1989]

I just remembered I tried section heading before. The underline of section title breaks build in section of parameters (i.e. Args:) because we are likely mixing up the Google style and Numpy style. As you posted, Parameter formatting is now broken and they are shown like type lengths: in your screen shot.

[coruscating]

Thanks for the info, I was wondering why the parameters were all messed up after I converted the heading. I tried a bunch of things and setting napoleon_use_param = False in conf.py seems to work:

Also, for the default values, I agree they can be very long sometimes. There are also examples like plotter := <qiskit_experiments.visualization.plotters.iq_plotter.IQPlotter object at 0x1763b8c70> which is confusing. Maybe we can just show the object type instead of the repr in cases like these?

[nkanazawa1989]

Ah this is close. I didn't consider the difference of :param: role and single :parameters: role. It indeed worked for parsing parameters under the section, but it broke other documentations with Type Annotations. We usually write type hints in the code, but they won't show up. I guess this is a bug though... For example this is constructor of StandardRB. Note that documentation of raises also looks strange. There is no napoleon_use_raises option. Probably we need to full scratch the documenter.

[nkanazawa1989]

Regarding the default value

how do we want to show a value like this?

[coruscating]

Hmm, I guess there's no easy fix then. We can leave it as possible future work.

For default values, I think showing numpy.linspace(-0.95, 0.95, 51) is a lot more readable than that block. But is there a way to do that besides manually calculating the start end and step size from the array? Or we can add an optional field in the experiment options docstring allowing override of the default display value in cases like this?

[nkanazawa1989]

It's likely tough to get args for ndarray factory. I implemented truncation in b1936a3

[coruscating]

I think this is really close! The truncated default values look nice. I noticed that InterleavedRB is showing StandardRB options as coming from itself instead, not sure why that's happening again.

[nkanazawa1989]

I noticed that InterleavedRB is showing StandardRB options as coming from itself instead, not sure why that's happening again.

Thanks for catching this. I fixed this once but 577ff71 reverted the logic by mistake. 99c4fe2 fixed class name.

[coruscating]

LGTM, thank you!