Qiskit / Qiskit/documentation

Move class attributes to a more relevant location

Open
#1,098 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

API docs infra 🏗️
Dominant language
Jupyter Notebook
Stars
106
Forks
223
Avg merge
1d 8h
Merged PRs (30d)
72

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the qiskit-sphinx-theme example_docs/api_example/electron.py output with the referenced HTML and the scripts/lib/api/snapshots/conversionPipeline.test.ts.snap entry. Trace the conversion pipeline and Attribute component handling, then verify that typed attributes render inline and appear in the Attributes section beneath the class description and constructor.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.