-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
Imported string constant has wrong docstring of str
#12020
Comments
Module level constants don't have docstrings, see How to document a module constant in Python?. So the REPL you included is correct: >>> my_var = "one_level"
>>> my_var.__doc__
"str(object='') -> str\nstr(bytes_or_buffer[, encoding[, errors]]) -> str\n\nCreate a new string object from the given object. If encoding or\nerrors is specified, then the object must expose a data buffer\nthat will be decoded using the given encoding and error handler.\nOtherwise, returns the result of object.__str__() (if defined)\nor repr(object).\nencoding defaults to sys.getdefaultencoding().\nerrors defaults to 'strict'."
You don't include an MRE does adding a docstring that Sphinx can parse as show in this post work?
Apparently this exact issue can be worked around with this answer. I'm not sure how things work with This question is a continuation of the much older #344 that also references this problem. |
Sorry, the example was not completely the code I was using and that I expected to work. I did have a docstring that was parsed by Sphinx for the original module, but obviously can't and doesn't get parsed when imported into another. I agree that what is the right docstring and the chain of inheritance can be controversial, and complicating the rules with magical filtering will break as many use cases as it fixes. Still, for this example, I'm not sure if an instance without docstring should fall back to the class's docstring (especially a built-in basic type), since instances and classes are different things. Although the As a user, I might have these options:
I also use already too many Sphinx workarounds, and instead of accumulating more, It would be great to find solutions at the source. I don't want to impose a solution, but it would be great if any of these were feasible:
|
The issue is likely from the ModuleAnalyzer. I don't think we actually follow correctly the imports for that. Unfortunately this is not easy to fix so I can only add this issue to the tracker... |
Same error here. |
Describe the bug
When a string constant is imported, sphinx cannot find the docstring of the original definition (in the module form where it was imported). Instead, it gives the docstring of
str
, which is misfitting and has a signature that does not render nicely.Expected behavior
The docstring of a string instance can't be the docstring of the
str
class.Cause
getdoc_internal
first tries the__doc__
attribute when looking for a docstring.sphinx/sphinx/util/inspect.py
Line 807 in d6f38ad
Demonstration:
This is related to #6495
How to Reproduce
This is specifically a problem when using recursion with a custom template with
members
(documenting also object typedata
).A less realistic but shorter way to trigger it is directly referencing the imported constant:
my_module/submodule1.py
my_module/submodule2.py
index.rst
.. autosummary:: my_module.submodule2.MY_CONSTANT
Environment Information
Sphinx extensions
Additional context
No response
Edit: I had forgotten to include the docstring I was using.
The text was updated successfully, but these errors were encountered: