readthedocs / readthedocs/sphinx-autoapi

Module table of contents are poorly formatted when long type hints are present

Open
#305 2 comments 3 reactions 0 assignees View on GitHub

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.

See this module for example.

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

  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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.