documentation
documentation copied to clipboard
Move class attributes to a more relevant location
In class docstring, you can write the Attributes:
to enumerate what attributes are available, like MyClass.my_attribute
. This is different than the class constructor arguments, like MyClass(my_attribute=1)
-- the attributes might not equal the class constructor args.
These attributes are similar to properties from @propery
methods, and from class attributes from code values like CLASS_ATTRIBUTE = 1
. But one big difference is they are defined in the class docstring directly, like this:
https://github.com/Qiskit/qiskit_sphinx_theme/blob/4606dfde7fcb0d7f65b7cc83f6c56f05aebda9fb/example_docs/api_example/electron.py#L18-L21
We correctly recognize them as <Attribute>
components, but we do two confusing things:
- If there's a type hint, we render the
type
as**type**
so it's bold. It would be better to inline the type so that it'ssize: str
. - The attributes show up in the class description, rather than the
## Attributes
section where we normally put things. This mirrors Sphinx's behavior, but I think Sphinx is confusing. Ideally we could move these attributes to instead live in the## Attributes
section underneath the class description and constructor.
This is the HTML:
https://github.com/Qiskit/documentation/blob/7dc37cae07db2754ecf21b120a6f5af6680f6760/scripts/lib/api/testdata/qiskit-sphinx-theme/stubs/api_example.Electron.html#L294-L309
This is the MDX from our conversion pipeline (this was before we had the <Attribute>
component set up):
https://github.com/Qiskit/documentation/blob/7dc37cae07db2754ecf21b120a6f5af6680f6760/scripts/lib/api/snapshots/conversionPipeline.test.ts.snap#L73-L87