Improve Sphinx config for autodoc and autosummary #132
Conversation
Eric-Arellano
requested review from
cbjuan,
d-kremer,
victor-villar,
jesus-talavera-ibm and
y4izus
as code owners
| :show-inheritance: | ||
|
|
||
| {% block attributes_summary %} | ||
| {% set wanted_attributes = (attributes | reject('in', inherited_members) | list) %} |
There was a problem hiding this comment.
We should be showing inherited attributes - they are useful for end users who don't care about inheritance chains. If you ever end up with too big of a class and want to leave off inherited members, you can set up this template
| @@ -1,5 +1,5 @@ | |||
| *************************************** | |||
| qiskit-ibm-transpiler API reference | |||
| ``qiskit-ibm-transpiler`` API reference | |||
There was a problem hiding this comment.
This makes it more clear that it's a PyPI package name
| # Options for autodoc. These reflect the values from Qiskit SDK and Runtime. | ||
| autosummary_generate = True | ||
| autosummary_generate_overwrite = False | ||
| autoclass_content = "both" |
There was a problem hiding this comment.
Docstring will be used for classes from both the class docstring and the constructor docstring
| autodoc_typehints = "description" | ||
| autodoc_default_options = { | ||
| "inherited-members": None, |
There was a problem hiding this comment.
This is how you tell .. autoclass:: to include inherited members
| autodoc_typehints = "description" | ||
| autodoc_default_options = { | ||
| "inherited-members": None, | ||
| "show-inheritance": True, |
There was a problem hiding this comment.
This results in classes saying which class they subclass
| napoleon_google_docstring = True | ||
| napoleon_numpy_docstring = False |
There was a problem hiding this comment.
This avoids the risk of docstring being misinterpreted.
While adding the new Qiskit addons, the docs team iterated on how best to configure Sphinx for more useful docs. You can see the result of this change at Qiskit/documentation#2342.
… (#133) Improve Sphinx config for autodoc and autosummary (#132) While adding the new Qiskit addons, the docs team iterated on how best to configure Sphinx for more useful docs. You can see the result of this change at Qiskit/documentation#2342.
While adding the new Qiskit addons, the docs team iterated on how best to configure Sphinx for more useful docs. You can see the result of this change at Qiskit/documentation#2342.