readthedocs / readthedocs/sphinx-autoapi
Module table of contents are poorly formatted when long type hints are present
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 494
- Forks
- 147
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
When a function has a very long call signature, potentially because it's making extensive use of type hints, the module table of contents generated by AutoAPI ends up being poorly formatted. The column with the function call signature in it becomes very wide, and the one-line docstring description gets squeezed off to the righthand side, potentially requiring scrolling to view.
Possible solutions might be stripping type hints from the call signature in the table of contents, or using a multi-line format for the call signature including type hints.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the generated module table of contents in the linked AutoAPI example and reproduce it with a function that has a long type-hinted signature. Trace the formatting responsible for the wide call-signature column; done means the one-line description remains visible without requiring horizontal scrolling, with coverage for the long-signature case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100