New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Custom types using typing.NewType are rendered inconsistently #9560
Comments
Adding this to # Workaround for https://github.com/sphinx-doc/sphinx/issues/9560
from sphinx.domains.python import PythonDomain
assert PythonDomain.object_types['data'].roles == ('data', 'obj')
PythonDomain.object_types['data'].roles = ('data', 'class', 'obj') 🙈🙈🙈 |
The workaround is also required the other way round, else Sphinx fails to resolve type annotations for attributes. from sphinx.domains.python import PythonDomain
assert PythonDomain.object_types['class'].roles == ('class', 'exc', 'obj')
PythonDomain.object_types['class'].roles = ('class', 'exc', 'data', 'obj')
assert PythonDomain.object_types['data'].roles == ('data', 'obj')
PythonDomain.object_types['data'].roles = ('data', 'class', 'obj') |
In python3.9, the newtype instance does not have correct information where it's defined.
But, it seems improved in 3.10 now:
So B should be represented as same as A. On the other hand, I don't understand why case C is needed. Why do you use |
Mostly for the reasons I described in my example:
|
In other words, I tried to find what worked best for me with the current version of Sphinx — but it looked like types are still pretty new and best practices for documenting them haven't settled down yet. |
Close #9560: autodoc: Allow to refer NewType with modname in py310+
Describe the bug
(It is probably easier to look at the reproduction, the screenshot, and the expected behavior than to read this description.)
In the following circumstances:
typing.NewType
autodata
directiveNo link to the custom type is generated, even though Sphinx should be able to do so — and does so in some very similar cases.
Also, there are inconsistencies between the rendering of this particular case and some very similar cases, as shown below.
How to Reproduce
sphinx-quickstart
conf.py
:autodoc_typehints = "description"
but setting it to"both"
yields interesting observations.)mymodule.py
:index.rst
:Expected behavior
Since A, B, and C are defined in the same module, I expect Sphinx to render their types consistently.
Currently:
NewType
instances B and C render differently from regular class A (module name not shown vs. shown); I'm only seeing this in the minimal reproduction, not in my actual use case, so I don't really care;Considering that:
I believe that:
NewType
instancesAfter a few hours of investigation, I suspect the link to C isn't generated because Sphinx looks up a xref of type "class", but C is documented as "data".
Indeed, this change causes the link to be generated (but obviously isn't the right fix):
I think the right fix could be:
Your project
See "How to reproduce"
Screenshots
OS
Mac
Python version
3.10.0rc1+
Sphinx version
v4.2.0+/8fd4373d3
Sphinx extensions
sphinx.ext.autodoc
Extra tools
—
Additional context
—
The text was updated successfully, but these errors were encountered: