Skip to content
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

docs: Include the relevant securesystemslib classes in docs #2167

Open
jku opened this issue Nov 5, 2022 · 2 comments
Open

docs: Include the relevant securesystemslib classes in docs #2167

jku opened this issue Nov 5, 2022 · 2 comments
Labels
documentation Documentation of the project as well as procedural documentation

Comments

@jku
Copy link
Member

jku commented Nov 5, 2022

Signer, Signature (and in future maybe most of Key) 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.Signature
seems to get us most of the way there...

@jku jku added the documentation Documentation of the project as well as procedural documentation label Nov 5, 2022
@theyashwanthsai
Copy link

Can I take up this issue?

@jku
Copy link
Member Author

jku commented Nov 9, 2022

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 docs to build docs locally (to docs/build/html/ IIRC). I assume you'll need to remove the autodoc_mock_imports = ['securesystemslib'] line from docs/conf.py but 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation of the project as well as procedural documentation
Projects
None yet
Development

No branches or pull requests

2 participants