API Documentation

[ArthurSens]

We've been offering Pyrra as a way to create and managed SLOs at Gitpod and one of the main sources of work for my team is explaining the SLO Spec 😅

It would be nice if we could automatically generate documentation from the API definition 🙂

[metalmatze]

Agreed, that would be helpful. What are you thinking of in particular? Is this something like the Prometheus Operator has for its APIs? https://prometheus-operator.dev/docs/operator/api/

The overall goal for Pyrra is to finally have an editor in its UI to create SLOs with: #87 I hope to get finally started with a proof of concept now that the generic rule generation for Grafana dashboards have been merged.

[ArthurSens]

Agreed, that would be helpful. What are you thinking of in particular? Is this something like the Prometheus Operator has for its APIs? https://prometheus-operator.dev/docs/operator/api/

Yes exactly!

The overall goal for Pyrra is to finally have an editor in its UI to create SLOs with: #87 I hope to get finally started with a proof of concept now that the generic rule generation for Grafana dashboards have been merged.

That will make things a lot easier indeed! GitOps is quite common way of managing Kubernetes resources, do you think this UI could also optionally generate the manifest instead of creating the resource directly?

[pharaujo]

(not affiliated) I've been using doc.crds.dev for auto-generated CRD docs, and I think it works pretty well. E.g. https://doc.crds.dev/github.com/pyrra-dev/pyrra

That said, I think this projects lacks a bit in the documentation area; I've had to go read the code a couple of times when I was unsure about how certain aspects of the SLO spec worked and, from experience, most end users won't bother doing that.