Open koliyo opened 6 years ago
I too would like to see this support. I need to specify the expected types for a bunch of data-descriptors, but inline type hinting per the above example does not currently work.
To be pendantic, the annotations on the initial post are instance attributes annotations. For class attributes you need to use ClassVar
.
class MyClass:
# You can optionally declare instance variables in the class body
attr: int
# This is an instance variable with a default value
charge_percent: int = 100
# You can use the ClassVar annotation to declare a class variable
seats: ClassVar[int] = 4
passengers: ClassVar[List[str]]
https://mypy.readthedocs.io/en/latest/cheat_sheet_py3.html#classes
If I've understood the documentation machinery correctly this would be huge for dataclasses. Big plus.
I'd also be interested in this feature :)
+1
In Sphinx 3.0 functionality similar to this was added to autodoc
. I know it's not a fix to this library, but I thought I'll leave it here too. It's nowhere near the whole thing and has some quirks that I'd like sorted out, but it looks promising for the dataclass use case at least. Sure beats having nothing.
# conf.py
extensions = [
...,
'sphinx.ext.autodoc',
]
autodoc_typehints = 'description' # show type hints in doc body instead of signature
autoclass_content = 'both' # get docstring from class level and init simultaneously
# documentation
@dataclass
class C:
"""Docstring."""
attr: dict
value: int
Some oddities and inconveniences I've found:
autoclass_content
is needed to have init typehints in documentation, even when the docstring is at the class level with parameter definitionsI'm sorry if it's in bad taste to essentially advertise other approaches on a library forum, but at least for me a solution is more important. It would be nice to know what does @agronholm think about the native implementation and this library's role?
So there is now: https://github.com/agronholm/sphinx-autodoc-typehints/pull/143
After a little tweak for some bad classes I deal with (david-yan/sphinx-autodoc-typehints#1) but otherwise it runs on my project.
It looks like presently #147 only looks at the Attributes:
in the class docstring while autodoc
checks the string literals immediately after the attribute/hint. Should the collection of the documentation be left to autodoc
and this change just pulls the content from there? (I'm just starting to get into Sphinx so I may be misassuming some structure here) I also kind of prefer the autodoc
formatting that places the type hint adjacent to the attribute name. I think this could be consistent with how sphinx-autodoc-typehints
puts parameter hints adjacent to the parameter name. Also, this doesn't have the behavior of stripping out the output generated by autodoc
.
All that said, thanks @david-yan for getting something started! Maybe I can find some time to build in some extra pieces.
@attr.s(auto_attribs=True, frozen=True, slots=True, eq=False)
class Emission:
"""Stores the emission of a signal including the emitted arguments. Can be
compared against a signal instance to check the source. Do not construct this class
directly. Instead, instances will be received through a channel created by
:func:`qtrio.enter_emissions_channel`.
Note:
Each time you access a signal such as ``a_qobject.some_signal`` you get a
different signal instance object so the ``signal`` attribute generally will not
be the same object. A signal instance is a ``QtCore.SignalInstance`` in
PySide2 or ``QtCore.pyqtBoundSignal`` in PyQt5.
Attributes:
signal: abc def
"""
signal: qtrio._util.SignalInstance
"""An instance of the original signal."""
I need this myself, but I have had very little time to spare for this project. I will look at the PR when time permits.
I can't really say I made any progress but I did poke around a bit to become minimally more familiar. The top two attributes in the image below (with zzz
in their descriptions) are being produced by sphinx-autodoc-typehints
while the bottom two are from autodoc
. The thing I feel like I need to know next is how to put regular old ReST in the :type:
and have it get processed rather than shown literally. I am guessing though that I am missing something pretty important about how this all works...
A PR for this would we welcome.
Any progress on this? Thanks!
Please check the comment I made right above yours. That's the latest progress.
For example
Does not currently generate type information when using sphinx + sphinx-autodoc-typehints