sphinx-doc / sphinx-doc/sphinx

Python default value of form <...> not rendered correctly

Open
#13,340 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

awaiting:response type:bug
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

Image

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

Open the contributing guide

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.