Always show type hints in docs #31
Conversation
Eric-Arellano
added
the
stable backport potential
There was a problem hiding this comment.
I'm not sure why this was added. None of the main Qiskit repos have it. It didn't change how qiskit/documentation works
There was a problem hiding this comment.
This was added to ensure reasonable titles for docs pages which only contain a function.
Below is a before and after of the docs page for qiskit_addon_obp.backpropagate:
With function.rst present:
Without it:
Notice the change in both the title and the navigation column on the left. Especially the latter I find very cumbersome as the fully resolved module names can become very long.
There was a problem hiding this comment.
I see. For what it's worth, it makes zero impact on how docs.quantum.ibm.com is rendered. I tested this out by first un-inlining a function & generating the docs w/o the template. Then I added back this custom template & regenerated - no change.
We show the full API name in the h1 for SEO purposes and so people know the import path. The left TOC looks like this:
So, I don't really have a preference because it doesn't impact docs.quantum.ibm.com. What would you prefer me to do?
There was a problem hiding this comment.
Okay I see. If it has no effect I suppose it does not matter and you can leave it like this. I assume we won't be publishing the docs in two places.
There was a problem hiding this comment.
I assume we won't be publishing the docs in two places.
Exactly. There will be a transition period for ~1-2 months as we migrate your guides to docs.quantum.ibm.com. Once that's done, we'll redirect GitHub Pages to the IBM site.
| autosummary_generate = True | ||
| autosummary_generate_overwrite = False | ||
| autoclass_content = "both" | ||
| autodoc_typehints = "description" | ||
| autodoc_typehints_description_target = "documented_params" |
There was a problem hiding this comment.
This is the main change
| autosummary_generate = True | ||
| autosummary_generate_overwrite = False | ||
| autoclass_content = "both" | ||
| autodoc_typehints = "description" | ||
| autodoc_typehints_description_target = "documented_params" | ||
| autodoc_member_order = "bysource" |
There was a problem hiding this comment.
I got rid of this because I think the default of alphabetical is more sensical, and it's what all the other non-addon projects use. You can read more at https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_member_order. Feel free to disagree!
There was a problem hiding this comment.
I don't remember for which specific case we added this but I am fine with going back to alphabetical
| napoleon_google_docstring = True | ||
| napoleon_numpy_docstring = False |
There was a problem hiding this comment.
Small performance optimization & reduces risk of unintended behavior
Pull Request Test Coverage Report for Build 11603399486Details
💛 - Coveralls |
Before, we would only show type hints for parameters that had dedicated docstring. There are a lot of parameters that don't have docstring—and sometimes don't need it because it's obvious—so it's best to no matter what show the docstring. This PR aligns the autodoc templates and config with the other addons like cutting. (cherry picked from commit a46b3d1)
Before, we would only show type hints for parameters that had dedicated docstring. There are a lot of parameters that don't have docstring—and sometimes don't need it because it's obvious—so it's best to no matter what show the docstring. This PR aligns the autodoc templates and config with the other addons like cutting. (cherry picked from commit a46b3d1) Co-authored-by: Eric Arellano <[email protected]>
See Qiskit/qiskit-addon-obp#31 for context.
See Qiskit/qiskit-addon-obp#31 for context. (cherry picked from commit eb1870d)
See Qiskit/qiskit-addon-obp#31 for context. (cherry picked from commit eb1870d) Co-authored-by: Eric Arellano <[email protected]>
Before, we would only show type hints for parameters that had dedicated docstring. There are a lot of parameters that don't have docstring—and sometimes don't need it because it's obvious—so it's best to no matter what show the docstring.
This PR aligns the autodoc templates and config with the other addons like cutting.