Qiskit / Qiskit/documentation

Always use a list for `Params` and `Raises` in API docs

Open
#1,361 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

Sphinx does not use an unordered list <ul> if there is only a single element:

screenshot_2024-05-13_at_4 35 21___pm_720

Compare that to:

screenshot_2024-05-13_at_4 35 03___pm_720

We think it would be more readable if we always used a bullet list, even when there is only one element:

screenshot_2024-05-13_at_4 36 59___pm_720

This is the path forward for adding indentation, https://github.com/Qiskit/documentation/issues/736.

--

This change should happen in the API conversion script, rather than the web app. That is, the change should happen in the children of the <Function> component, rather than the component itself making this transformation. We would update processHtml.ts to convert single values into a <ul> with one <li>.

This should be done for Params, Raises, probably Yields, and probably more of https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#docstring-sections. But it should not be added to everything. For example, return type should not have indentation since it never has >1 element.

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 reading processHtml.ts and the children of the component in the API conversion path. Check how Sphinx sections such as Params, Raises, and Yields are currently converted, while keeping return type unchanged. Done means eligible single-value sections render as a

    containing one
  • , without changing the web component itself.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.