documentation icon indicating copy to clipboard operation
documentation copied to clipboard

Move class attributes to a more relevant location

Open Eric-Arellano opened this issue 4 months ago • 0 comments

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:

  1. 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's size: str.
  2. 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.
Screenshot 2024-03-26 at 1 18 24 PM

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

Eric-Arellano avatar Mar 26 '24 17:03 Eric-Arellano