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

Always use a list for Params and Raises in API docs #1361

Open
Tracked by #479
Eric-Arellano opened this issue May 13, 2024 · 0 comments
Open
Tracked by #479

Always use a list for Params and Raises in API docs #1361

Eric-Arellano opened this issue May 13, 2024 · 0 comments

Comments

@Eric-Arellano
Copy link
Collaborator

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, #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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant