readthedocs / readthedocs/sphinx-autoapi
Bad construction of return type in `AutoapiSummary` leads to bad signature mangling with autodoc
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 494
- Forks
- 147
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
Hello,
I noticed that module-level functions that were summarized with AutoapiSummary would display their return type instead of their parameters list.
I.e.:
my_function(→ Collection[MyType])
Instead of:
my_function(arg1, arg2, arg3)
This issue only affects summarized functions or methods that have a return type.
I identified this change as the problem: https://github.com/readthedocs/sphinx-autoapi/commit/72707183744ff9daabffc787f9f1ce094630e547#diff-dfb37c7639343e616e90196421ee72877ede504a96f6485b14b537ba7e7c0b65R28.
This code appends the return type to the signature being built, prefixed with an "arrow".
The linked change replaces the -> plain ASCII arrow with the Unicode arrow →.
Afterwards, the signature is mangled by Sphinx's autodoc mangle_signature.
The problem is that this Sphinx's method expect the return type to be appended with an ASCII arrow.
Then, its regexes fail and we and up with what I showed above.
Replacing the Unicode arrow with the ASCII arrow fixed the problem.
Since I'm not sure why this Unicode was introduced in the first place, I don't know if this fix is enough.
It came with adding support for overloaded methods, where the list of parameters is replaced with the Unicode ellipsis character; and the arrow was replaced with the Unicode arrow at the same time.
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
Inspect the change linked in the issue and Sphinx autodoc's mangle_signature behavior first. Reproduce the problem with summarized functions or methods that have return types, including the overloaded-method case mentioned in the report. Done means signatures retain their parameter list while return types and overload representations remain correct.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100