Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move class attributes to a more relevant location #1098

Open
Tracked by #479 ...
Eric-Arellano opened this issue Mar 26, 2024 · 0 comments
Open
Tracked by #479 ...

Move class attributes to a more relevant location #1098

Eric-Arellano opened this issue Mar 26, 2024 · 0 comments

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented Mar 26, 2024

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:

<dl class="py attribute">
<dt class="sig sig-object py" id="api_example.Electron.size">
<span class="sig-name descname"><span class="pre">size</span></span><a class="headerlink" href="#api_example.Electron.size" title="Link to this definition">#</a></dt>
<dd><p>How big the Electron is.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="api_example.Electron.name">
<span class="sig-name descname"><span class="pre">name</span></span><a class="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):

<span id="api_example.Electron.size" />
### size
How big the Electron is.
**Type**
str
<span id="api_example.Electron.name" />
### name
What the Electron is called.

github-merge-queue bot pushed a commit that referenced this issue Mar 26, 2024
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.
@Eric-Arellano Eric-Arellano changed the title Improve rendering of class attributes Move class attributes to a more relevant location May 2, 2024
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: No status
Development

No branches or pull requests

1 participant