-
Notifications
You must be signed in to change notification settings - Fork 272
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
Improve ngclient/metadata docs #1543
Comments
Some proposals from @jku:
We could document the main classes (Metadata, all signed derivatives) page-per-class and then have one page for the "helper classes
In general sphinx wants us to document our constructors in the class docstring and not in
|
https://theupdateframework.readthedocs.io/en/stable/ is nothing yet: needs to be configured somehow I suppose? EDIT: this also makes sense considering no release includes the config yet... they claim it's automatic:
so... let's get a release out |
Yes, exactly, I just tried manually building stable and the version it checked out is: |
Quick review of metadata doc:
And one more thing on ngclient:
|
This probably won't work: autodocs :inherited-members: does not apply to attributes so e.g. |
sphinx autodoc can not automatically document the types of python instance attributes -- this makes sense when you think about the data autodoc has available (for functions the types are annotated but for attributes it would have to run a static type check to figure the types out) Since in Metadata API we have documented the attributes, and not constructor arguments (because they are typically the same), we are now in this documentation situation:
(╯°□°)╯︵ ┻━┻ Even if we document the the attribute type in a way sphinx understands, it uses huge amounts of vertical space per attribute: it just looks quite awful with the sort of classes we have. I think I might suggest documenting the arguments (which are dcoumented nicely with types and in reasonable vertical space), and just stating that they are also instance attributes... |
Description of issue or feature request:
The documentation that will hopefully be hosted on readthedocs after the work on #1517 is done needs some further improvement:
The text was updated successfully, but these errors were encountered: