You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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's size: 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.
<spanclass="sig-name descname"><spanclass="pre">size</span></span><aclass="headerlink" href="#api_example.Electron.size" title="Link to this definition">#</a></dt>
<spanclass="sig-name descname"><spanclass="pre">name</span></span><aclass="headerlink" href="#api_example.Electron.name" title="Link to this definition">#</a></dt>
<dd><p>What the Electron is called.</p>
</dd></dl>
This is the MDX from our conversion pipeline (this was before we had the <Attribute> component set up):
These render worse than we realized. This PR creates a baseline so that
we can see how our changes improve things over time.
See #1098 for the tracking
issue.
These render worse than we realized. This PR creates a baseline so that
we can see how our changes improve things over time.
See Qiskit#1098 for the tracking
issue.
In class docstring, you can write the
Attributes:
to enumerate what attributes are available, likeMyClass.my_attribute
. This is different than the class constructor arguments, likeMyClass(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 likeCLASS_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:type
as**type**
so it's bold. It would be better to inline the type so that it'ssize: str
.## 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:
documentation/scripts/lib/api/testdata/qiskit-sphinx-theme/stubs/api_example.Electron.html
Lines 294 to 309 in 7dc37ca
This is the MDX from our conversion pipeline (this was before we had the
<Attribute>
component set up):documentation/scripts/lib/api/__snapshots__/conversionPipeline.test.ts.snap
Lines 73 to 87 in 7dc37ca
The text was updated successfully, but these errors were encountered: