Repository navigation
docs: Include the relevant securesystemslib classes in docs #2167
Description
Activity
Can I take up this issue?
sure, please do!
- sphinx and autodoc are ... unique, so you'll likely have to experiment a bit to get results: autodoc docs are here https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html . Feel free try something, and make a draft PR with whatever you have if you get stuck.
- Sources are in docs/api/ . Run
tox -e docsto build docs locally (to docs/build/html/ IIRC). I assume you'll need to remove theautodoc_mock_imports = ['securesystemslib']line fromdocs/conf.pybut not 100% sure (as I said autodoc is a bit strange) - One option is to add these classes to
docs/api/tuf.api.metadata.supporting.rst(which becomes https://theupdateframework.readthedocs.io/en/latest/api/tuf.api.metadata.supporting.html) - another option might be to add a new docs page altogether for Securesystemslib classes
- whichever options is best, it should be clear to reader these classes are from Securesystemslib -- Maybe a title like "Supporting classes from Securesystemslib" is enough?
Signer,Signature(and in future maybe most ofKey) are really part of the Metadata API but are technically implemented in securesystemslib.We should either include those in the python-tuf API docs, or create similar docs for securesystemslib and link to those (but we don't want to document the rest of securesystemslib API in the same manner).
The former (including in python-tuf api docs) might be quite simple as plain:
.. autoclass:: securesystemslib.signer.Signatureseems to get us most of the way there...