Document functions on module pages

[Eric-Arellano]

See #10455 for the motivation:

1. Better user experience.
2. Faster docs build because this results in about 270 fewer pages. From 4:30 to 4:10. This benefit will be much bigger when switching to the new Furo theme because it works around the O(n^2) behavior of the left side bar, where n is # of HTML pages, as described in Furo: investigate slow builds qiskit_sphinx_theme#328.

This does not migrate the visualizations module, though, since those functions tend to have huge docstrings with visuals included.

Some of our functions are documented on module pages but come from submodules, e.g. qiskit.circuit.random.random_circuit being documented on qiskit.circuit. To make it clear that you cannot directly import qiskit.circuit.random_circuit, this PR also changes our config to show the module path in code objects:

Follow up PRs should consider re-exporting those submodule members in the top-level module so that we can revert this config.

[coveralls]

Pull Request Test Coverage Report for Build 5679422072

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 111 unchanged lines in 9 files lost coverage.
• Overall coverage decreased (-0.02%) to 85.914%

---

Files with Coverage Reduction	New Missed Lines	%
qiskit/circuit/library/n_local/efficient_su2.py	1	94.74%
qiskit/extensions/unitary.py	1	93.75%
crates/qasm2/src/lex.rs	4	90.38%
qiskit/circuit/library/n_local/two_local.py	5	87.8%
qiskit/circuit/library/n_local/qaoa_ansatz.py	9	88.89%
qiskit/transpiler/passes/routing/stochastic_swap.py	9	95.67%
qiskit/circuit/library/evolved_operator_ansatz.py	11	85.95%
crates/qasm2/src/parse.rs	18	96.67%
qiskit/circuit/library/n_local/n_local.py	53	84.65%

Totals
Change from base Build 5657291250:	-0.02%
Covered Lines:	73046
Relevant Lines:	85022

---

💛 - Coveralls

[qiskit-bot]

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

• @enavarro51
• @Cryoris
• @ElePT
• @Qiskit/terra-core
• @ajavadia
• @ikkoham
• @mtreinish
• @nkanazawa1989
• @woodsp-ibm

[jakelishman]

Thanks Eric, this looks like a solid start. I think we'll want to do more passes in the future improving the stories on these documentation pages, but that's definitely for another day. I've found that putting more of these methods on the same page seems to exacerbate CSS problems in the Pytorch theme, but hopefully that'll all be fixed by Furo anyway.

There's a few places where I think we need to be careful about .. currentmodule handling that autosummary would previously paper over, but mostly this looks fine to me.

[Eric-Arellano]

Thanks, Jake! You're spot on.

[Eric-Arellano]

Huh..the last commit resulted in a maximum recursion error 😱 But @jakelishman I suspect it wouldn't solve the UX problem either way -- I think the functions would still only show the function name, rather than the full or relative module, so it would make the import path misleading.

--

Alternative idea. What if we stopped using .. currentmodule:: in general? That way our docs show the full module path, like this:

Imo, that is a better user experience because it allows you to immediately see how to import the code object. That's especially useful on long pages where you forget what module you're on.

Yes, it's more verbose in our __init__.py, but that doesn't seem like a big deal.

I would split that out as a dedicated "prefactor" PR.

[jakelishman]

The UI of what is displayed is a bit of a separate question to the currentmodule directive, which tells Sphinx what module the contained objects should be considered as part of. If you want all the module names shown, then we should set add_modules_names=True to the root conf.py. I'd worry a little about that being very noisy for individual functions, but it could be ok, and it's not my call anyway.

For functions where it might not be clear how they're imported from the docs structure, I think that probably more indicates that the current import structures in Qiskit / incomplete explanations in the documentation, tbh. qiskit.circuit.random.random_circuit probably should just be available at qiskit.circuit.random_circuit.

[jakelishman]

I flicked through all the built documentation pages, and this looks like a good improvement to me. There's of course places where our styling could be improved, but we're hoping the switch to Furo will improve a lot of that immediately, and make the rest rather a lot easier to improve.

I pushed up a minor change to add some more autofunction calls in a couple of files that I spotted them in.