-
Notifications
You must be signed in to change notification settings - Fork 19
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
Model fields and type hints #109
Comments
Not using |
We may finally have what we are looking for in Sphinx 3! It introduced a new extension to Doc comments don't quite work, and if we were to document attributes, they won't inherit from a dataclass to another. Additionally, the type hints show the full name of the object, e.g. |
We could indeed start using the builtin extension fully. It is essentially enabled by disabling the 3rd-party autodoc typehints and specifying two options: autodoc_typehints = 'description'
autoclass_content = 'both' Here are some problems that need to be resolved:
Most of them seem like issues with or additions to Sphinx itself, so maybe we ought to wait a bit and make the change once the issues have been resolved. Seems like Sphinx 3.2 might be the version when all this is resolved. |
With this shift, we could also have a look at can Napoleon and Autodoc be used to document function return types as well. Currently the Numpy style requires the return type to be present, but it shouldn't need to be so. An issue: sphinx-doc/sphinx#7077 This can be alleviated by using # Signature
def foo(...) -> Tuple[type, another]
# Numpy docstring
"""
Returns
-------
Tuple[type, another]
this returns things
"""
# Hack around napoleon
"""
:return: this returns things
""" |
About type hints - it would be great to add Easy PR:
|
Getting errors from the spotify query with your hack in the serialise.py for Json track list. |
I'm not sure what you are referring to, @MarkoShiva. If this is a bug, would you mind opening a dedicated issue with some more information? Which spotify query? What hack? Which errors? |
An update: due to other changes in Tekore, inheriting the docstrings of other libraries is no longer an issue. I don't think we have any inheritance from other libraries now. Turning off fully qualified names was fixed recently, but some discussion of it still not working is ongoing. If that issue's ok, then we are left with just properties missing their return type, which seems to be delayed until at least Sphinx version 4. Where it hurts us most is in |
And recently the support for property return type hints was added too! This all is to be expected in Sphinx 4.0, released in April, so let's look at changing the doc configuration and finally resolving this issue then. |
Sphinx 4 was released just now, but it seems that the newly introduced option |
Just for reference, I've opened sphinx-doc/sphinx#9268. Edit: now closed and waiting for a release on the 12th. |
I've now pushed the type hint improvements. The model parameters are now also documented in the description, which would allow for us to document the fields, but the docs are not inherited. We should maybe look into a solution for that as well. Maybe Attrs? |
It seems too difficult to really be worth it. The attributes are documented in the Spotify Object Model. We should link to it, but that ought to be enough. |
Done in a0e8491 |
Dataclass fields, and subsequently type hints are not shown on the documentation (example). It would be very useful to view them and even jump to other definitions with similar links that are available elsewhere.
The text was updated successfully, but these errors were encountered: