Automated generation of API docs

[laurentsimon]

If there's a tool to auto-generate / update documentation based on the doc in the code, that'd be helpful.

@mihaimaruseac @spencerschrock

[spencerschrock]

Since I happened to look at sigstore-python's docs today, would something like their system work?

uses pdoc to generate HTML documentation for the public Python APIs.

Which they run as part of their CI and deploy to github pages at https://sigstore.github.io/sigstore-python/sigstore.html https://github.com/sigstore/sigstore-python/blob/f9e313eab473503ec688f5a12ed21c81ad9a81f2/.github/workflows/docs.yml

[mihaimaruseac]

This looks great! Let's do it.

I'll add to the v1 release milestone, since it's good to release with some documentation

[spencerschrock]

There is some work towards this done in #279, but there are a few open questions still:

• [ ] We may want to add some docstrings to the various __init__.py files
• [ ] Do we only want to generate new documentation for tags, or for any change to main
• [X] I'm ignoring certain test files with pdoc CLI args, but there are other ways of ignoring files.
• [X] Setting up the GitHub Pages and where this model_signing documentation will live, compared to any future slsa_for_models documentation. (https://github.com/sigstore/community/pull/480 and https://github.com/sigstore/community/pull/481)

[spencerschrock]

You can see an example of the documentation generated in the action run by downloading the artifact.

[mihaimaruseac]

This looks good to me, thank you!

I think we might need to reorder the files in the repo as they're not in a good shape for packaging to a wheel. I'll read more about this and experiment to see if we can avoid it, otherwise we need to decide if we wait for #240 or we'd have it rebase again

[spencerschrock]

279 has been rebased to account for the layout change in #283, and now makes use of hatch.

You can see the latest action run and artifact from the PR.

[spencerschrock]

https://sigstore.github.io/model-transparency