Close #9075: autodoc: Add a config variable autodoc_unqualified_typehints #9931
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Now python domain supports the "~" prefix at the beginning of the typehints of the function signatures: .. py:function:: func(x: ~typing.Dict) It's rescognized as the same as python reference roles do (ex. :py:class:`~typing.Dict`).
tk0miya
added
type:enhancement
tk0miya
commented
Dec 2, 2021
tests/test_ext_autodoc_configs.py
Outdated
| ' :type: int', | ||
| '', | ||
| '', | ||
| '.. py:class:: Math(s: str, o: ~typing.Optional[~typing.Any] = None)', |
There was a problem hiding this comment.
Internally, autodoc generates a typehints leading ~ if the option is enabled. This is a special notation to suppress prefix (modname and leading class name) of the typehint. It's like the ~ of :py:class: role (ex. :py:class:`~io.StringIO` ).
tk0miya
commented
Dec 2, 2021
tk0miya
commented
Dec 2, 2021
doc/usage/extensions/autodoc.rst
Outdated
| .. confval:: autodoc_unqualified_typehints | ||
|
|
||
| If True, the leading module names of typehints of function signatures (ex. ``io.StringIO`` -> | ||
| `StringIO``). Defaults to False. |
There was a problem hiding this comment.
To keep compatibility, I'll disable this feature by default during 4.x. And I'd like to enable this since 5.x.
tk0miya
force-pushed
the
9075_autodoc_unqualified_typehints
branch
from
859d1e4
to
f50c26e
Compare
To make the generated function signatures simple, this adds a new parameter `smartref` to sphinx.util.typing:stringify() to suppress the leading module name from typehints.
To make the generated function signatures simple, this adds a new parameter `unqualified_typehints` to sphinx.util.inspect: stringify_signature() to suppress the leading module name of typehints.
…fied_typehints If autodoc_unqualified_typehints feature enabled, autodoc suppresses the leading module names of typehints of function signatures (ex. `io.StringIO` -> `StringIO`)
tk0miya
force-pushed
the
9075_autodoc_unqualified_typehints
branch
from
f50c26e
to
c71ff1c
Compare
tk0miya
commented
Dec 3, 2021
tk0miya
added a commit
to tk0miya/sphinx
that referenced
this pull request
Dec 18, 2021
tk0miya
added a commit
to tk0miya/sphinx
that referenced
this pull request
Dec 18, 2021
tk0miya
added a commit
that referenced
this pull request
Dec 19, 2021
doc: Update explanation of autodoc_unqualified_typehints (ref: #9931)
|
I discussed the option name with @shimizukawa in the hack day. And he proposed to me to rename this option to use "short name" instead of "unqualified" because "unqualified" is not easy to understand. |
tk0miya
added a commit
to tk0miya/sphinx
that referenced
this pull request
Dec 24, 2021
tk0miya
added a commit
that referenced
this pull request
Dec 25, 2021
autodoc: Rename autodoc_unqualified_typehints to autodoc_typehints_format (refs: #9931)
AA-Turner
pushed a commit
to AA-Turner/sphinx
that referenced
this pull request
Dec 29, 2021
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Feature or Bugfix
Purpose
leading module names of typehints of function signatures (ex.
io.StringIO->StringIO)