sphinx-doc / sphinx-doc/sphinx
Python default value of form <...> not rendered correctly
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
Description
If in function signature I put <anything goes here> then the signature will not be rendered correctly. This means that intersphinx links will also not work.
This is an issue since the default repr of python objects is usually <...> and it is sometimes defined so in packages (for example the scipy.sparse arrays have such a repr. Together with autodoc is a recipe for bad docs.
I'd expect that either sphinx deals with such defaults value reprs or that a warnings be emitted so users aren't confused.
Related issue
If I'm already on the topic, another issue you might want to address is that autodoc can create confusing default values. For example, if I have an instance of the following A as a default value:
class A:
def __repr__(self) -> str:
return "0, y: ~typing.Any = 1"
This will cause autodoc to create another parameter entry in the documentation. This is just an example for how __repr__-s found in the wild can be bad for autodoc. It would be good if the autodoc sanitized the default values it generates. If you'd like I'll open a separate issue for this.
How to Reproduce
Minimal reproducer:
In check_sphinx/__init__.py:
from typing import Any
class A:
def __repr__(self) -> str:
return "0, y: ~typing.Any = 1"
a = A()
def compare(x: Any = a) -> str | None:
"""Docstring."""
...
In conf.py:
extensions = ['sphinx.ext.autodoc']
In index.rst
Title
=====
.. py:function:: bloo(x: ~typing.Any = hi) -> None
This is a function.
.. py:function:: blah(x: ~typing.Any = <hi>) -> None
This is a function.
.. autofunction:: check_sphinx.compare
Yields
Environment Information
I used both sphinx from `master` and from `PyPI` (8.1.3).
Platform: linux; (Linux-6.8.0-51-generic-x86_64-with-glibc2.39)
Python version: 3.13.0 (main, Oct 16 2024, 03:23:02) [Clang 18.1.8 ])
Python implementation: CPython
Sphinx version: 8.1.3
Docutils version: 0.21.2
Jinja2 version: 3.1.5
Pygments version: 2.19.1
Sphinx extensions
The first issue I describe doesn't need extensions.
The second is autodoc related.
Additional context
No response
Contributor guide
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 with the minimal reproducer in check_sphinx/init.py, conf.py, and index.rst, then run the autodoc and Python-domain rendering paths against both default forms. Compare how angle-bracket reprs are parsed and how the generated signature is rendered. Done means the signatures render correctly, intersphinx links remain usable, and the reproducer is covered by a regression test.
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
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100