haydentherapper
commented
1 year ago The first part of this is a dup of https://github.com/sigstore/docs/issues/117
I do like that idea of exploring automation and having developer focused documentation come from the repos!
Description
The documentation website appears to be solely focused on the user's perspective, rather than also incorporating the developer's viewpoint as well. Although there is a Swagger documentation available at sigstore.dev/swagger/, it is not accessible from the main documentation website. This can be fixed by including an additional link in the header of the website as shown below.
Additionally, although it is mentioned in sigstore's GSoD proposal that finding a way to “to ensure that documentation does not go out of date” is out of the scope of the GSoD project, it is actually very straightforward to incorporate a way to automate the generation of documentation, at least from a developer's perspective. This is based on my experience with automating the documentation for the Talawa docs website as part of GSoD 2022 of which I was a mentor.
To keep pace with the changes that occur with any number of pull requests, CI/CD pipelines can be used to automate the documentation process. Here's how it works (as illustrated in the accompanying figure):
First, when making a pull request a GitHub Action checks for any Go files in it and sees if they have comments in a specific format. If the checks are unsuccessful and changes to the files will be requested.
If the pull request is successful, another GitHub Action generates static HTML files from the comments in the changed and/or added files using the godoc command. These artefact files are then sent to the sigstore documentation repository.
Finally, another GitHub Action in the sigstore docs repository collates the HTML files and organises them into a pre-specified template, creating a comprehensive documentation page that is added to the sigstore documentation site.
Sigstore's constituent repositories (Cosign, Fulcio, Rekor, Gitsign, etc.) can automatically generate documentation utilising tools such godoc in the pipeline described above. Since the constituent repositories are all written in Go, the same pipeline with the Godoc library would suffice for each of the four aforementioned repositories. In the same vein, It would not be particularly difficult to make modifications for the repositories written in Python (sigstore-python) or Rust (sigstore-rs) or Java (sigstore-java) or another language for that matter. In all these cases, it would involve modifying of workflows found in the Talawa API and then just applying them to our use cases. This works well due to the similarity between the websites that host both Talawa and sigstore.