Show missing type hints & inline class base class in API docs #13483
Conversation
There was a problem hiding this comment.
See Qiskit/documentation#2377 for a preview of how this changes *the Git diff for the 1.3 dev docs.
| # 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", | ||
| } |
There was a problem hiding this comment.
Feel free to disagree on this. The Runtime devs thought in Qiskit/qiskit-ibm-runtime#1877 that the full type is way too long to actually be understandable. I agree with them, and I think it's better to explain pubs in guides like https://docs.quantum.ibm.com/guides/primitive-input-output. But there's an argument for having the full type.
There was a problem hiding this comment.
I agree with the aliases, the full type is not really helpful.
Pull Request Test Coverage Report for Build 11979624934Details
💛 - Coveralls |
|
One or more of the following people are relevant to this code:
|
| # 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", | ||
| } |
There was a problem hiding this comment.
I agree with the aliases, the full type is not really helpful.
Oops, I meant to say how it changes *the Git diff to see a before and after. |
Eric-Arellano
added
documentation
| # Only add type hints from signature to description body if the parameter has documentation. The | ||
| # return type is always added to the description (if in the signature). | ||
| autodoc_typehints_description_target = "documented_params" | ||
|
|
There was a problem hiding this comment.
Is there a chance we are exposing parameters that were being kept private on purpose with this change? Else I wonder why this variable would have been set originally.
There was a problem hiding this comment.
When we swapped from using the third-party sphinx-autodoc-typehints to the built-in sphinx.ext.autodoc support for this, I think I just set the options that caused the most similar behaviour to before (#9705).
There was a problem hiding this comment.
Is there a chance we are exposing parameters that were being kept private on purpose with this change?
It wouldn't make sense to me to have certain parameters be private and others public. I suspect certain parameters aren't being documented simply due to oversight, or perhaps people thinking it's intuitive so it doesn't warrant docstring.
Also, the parameters are already in the docs as part of the signature. The only change this PR makes is showing their type hints.
The API docs were leaving off some important information:
.. autoclass::on a module page; it was already fine for.. autosummary::.None. These type hints are useful.To land this PR, I had to make a fix similar to #10772 to fix ambiguous type hints.
I also set up aliases for the extremely long types for
EstimatorPubLikeandSamplerPubLike. See Qiskit/qiskit-ibm-runtime#1877 for more context on that problem.