sphinx
sphinx copied to clipboard
sphinx-doc
Inherited docstrings of TypeDict subclasses are missing
Is your feature request related to a problem? Please describe. Currently sphinx understands to produce the documented annotations of a TypedDict subclass thanks to #7486
TypedDict subclasses can themselves be used as parent classes of another. A problem arises here in that sphinx will inline the members of the parent class, but doesn't include the docstrings for those members.
Describe the solution you'd like I'd like the docstrings to carry over into the subclass
Describe alternatives you've considered Copying all of the member annotations from the parent into the child, ie. not using inheritance at all.
Additional context Contrived example:
class Food(TypedDict):
""" this is a food """
cook_name: str
""" The name of the maker of the food """
price: int
""" How much the food cost """
class Tacos(Food):
""" a taco variety of food """
toppings: List[str]
""" things that go on the taco"""
When generating autoclasses, the Tacos doc includes mention of the cook_name and price, but not their docstrings
I understand this might be very complicated to make work, due to how TypedDict subclassing works, but I felt it's worth a shot to file this as an RFE anyway.
If using the :inherited-members: directive, I end up with all of the methods from dict (which isn't what I want at all but maybe I could filter those out) but the docstrings from the parent class's members are still missing.
Just wanted to say, your example of putting the marker as strings in the code vs. docstring solved my problem with TypedDict creating duplicated attributes. Can this be found anywhere in the current docs for sphinx? If not, we should consider adding it.
I only happened to know to use string literals for field docstrings by having seen it that way once before long ago. I'm not sure I've ever seen it declared as the official syntax, so I cannot point you to any reference material I'm sorry to say.
@jmahlik when you say "your example of putting the marker as strings in the code vs. docstring " what do you mean? could you link to this example? I'm hitting the same problem
Can this be found anywhere in the current docs for sphinx?
It is described in autodoc extension's document: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autofunction
@jmahlik when you say "your example of putting the marker as strings in the code vs. docstring " what do you mean? could you link to this example? I'm hitting the same problem
It is the example above in the original post from @obriencj. Putting a literal string below the attribute will result in sphinx making nice docs for a TypedDict. But as the post mentions, subclasses end up missing the parent's attributes.
Comments like this also work. flox = 1.5 #: Doc comment for Foo.flox. One line only.
