sphinx-doc / sphinx-doc/sphinx

Inconsistent output for optional parameters/attributes

Open
#11,522 2 comments 2 reactions 0 assignees View on GitHub

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

The type of an optional parameter in

:param Optional[str] bar: The bar parameter

will be output differently than that of an optional attribute:

.. attribute :: bar
   :type: Optional[str]

or when there's a type annotation on the paramter itself:

def foo(bar: Optional[str]):
   ...
How to Reproduce

The following Python sourceode:

class Test:
    """
    Test class.
    """
    def foo(self, bar: Optional[str]):
        """
        .. attribute :: bar
           :type: Optional[str]

            The bar attribute

        :param Optional[str] bar: The bar parameter.
        """
        pass

when incorporated into a Sphinx project via .. automodule:: etc. gives the following HTML output:

Bildschirmfoto 2023-07-26 um 20 01 27

The type annotation Optional[str] should be displayed consistently as str | None in all three spots, instead of as Optional[str] for :param:, and str | None for .. attribute and type annotations in the function signature.

Environment Information
`sphinx-build --bug-report` gives:


Platform:              darwin; (macOS-10.16-x86_64-i386-64bit)
Python version:        3.9.13 (v3.9.13:6de2ca5339, May 17 2022, 11:23:25)
[Clang 6.0 (clang-600.0.57)])
Python implementation: CPython
Sphinx version:        7.1.0
Docutils version:      0.18.1
Jinja2 version:        3.1.2
Pygments version:      2.15.1
Sphinx extensions

No response

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 Python source example and reproduce it in a Sphinx project using the mentioned .. automodule:: entry point. Compare the HTML for the parameter, attribute, and function signature; the work is done when all three display Optional[str] consistently as str | None.

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
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.