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