-
Notifications
You must be signed in to change notification settings - Fork 2.1k
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
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
autodoc_typehints cause bogus Return type
sections to be generated in autoclass
#12472
Comments
Did you set the default value of
but to me it isn't entirely clear if this should only apply for the Besides that, this is a somewhat complicated signature:
With a generic and a metaclass, what should the run-time return type be exactly? (Here it should -maybe- be said, that linking to a repo doesn't make for an MRE and it makes life a lot simpler if you can distill an MRE that can be copy pasted and executed with only the non-default configuration settings included, otherwise reports require Sphinx contributors/triagers to extract an MRE themselves and the report becomes mostly useless to other potential future readers...)
This is a bit of a special case because it's a class constructor thus the generated docs also depend on other options like Anyway, sometimes autodoc does get the signatures wrong in which case the simplest workaround might be pasting the desired signature into the autoclass directive explicitly. This does have its own drawbacks but often it's the surest way of not having to change project wide settings to satisfy a single bugged signature. In case you missed it the Sphinx repository has issue #11991 pinned at the top. It groups these kinds of bugs but some more diagnoses/research would be needed to ascertain if this is a duplicate of a previously reported issue or if it's something new. |
An instance of the
I do not understand your question. I presume when documenting a class no one would want to document a return value as the return type of instancing a class is an instance of the class. What's really strange to me is that return values are not generated for the other very-similar class definitions, like
I did not. I didn't figure I'd have to. But that works, thanks. |
From a documentation POV it's a somewhat common option to omit an explicit
The autodoc/napoleon configuration values are mostly orthogonal but they're not always independent. If a superclass has a docstring in one inheritance but not in another
Always glad to help a fellow Sphinx user :D |
I'd say it's a bug but I don't really have time (nor the mood) to fix this one. Autodoc is great in general but it suffers from a lot of issues that when you try to fix one, the code becomes messy. I still haven't written a formal RFC for the next autodoc version so I'll add it to the list of known issues. |
Is there any way to turn off deduced return type on a per-class basis? |
I don't remember but I don't think so. I'm not sure this autodoc option is actually picked up at the level of the class, but maybe writing your own documentation for |
|
As I said before the most effective way of doing this is pasting the signature directly into the autodoc directive (likely having to manually adjust the module.class syntax for the types if you want to keep all the links working). This solution can require that your .rst isn't just a top-level Could you please include a link to the example class in the docs (if you've published this problematic build) and its .rst file? |
I'm documenting a class. I do not want a signature to show up at all. I want to turn it off, not correct it. The RST: https://github.com/cocotb/cocotb/blob/master/docs/source/library_reference.rst#python-triggers |
There's a way to select the docstring applied to a given I looked at your source code and I'd say Sphinx is working as expected. Your Additionally if you want to remove |
This issue was moved to a discussion.
You can continue the conversation there. Go to discussion →
Describe the bug
When
autodoc_typehints = "description"
, aReturn type:
field is generated for an autoclass, which is nonsense, and the generated return type is not even correct. Changing toautodoc_typehints = "none"
resolves the issue.The autoclass is described simply as
The docstring is located on the class itself:
How to Reproduce
Environment Information
Sphinx extensions
Additional context
No response
The text was updated successfully, but these errors were encountered: