sphinx-doc / sphinx-doc/sphinx
Inconsistent output for optional parameters/attributes
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:
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
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 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