controller-tools
controller-tools copied to clipboard
kubernetes-sigs
Tool to generate API documentation in markdown
It would be useful to be able to generate API documentation in markdown for all custom resource types under pkg/apis/... based on the comments in the types.go source.
Largely inspired by how the prometheus-operator auto-generates its API documentation. https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md https://github.com/coreos/prometheus-operator/blob/master/cmd/po-docgen/api.go
As suggested by one of our users, the initial plan was to port over the above utility from the prometheus-operator into the Operator SDK, but it seems like this might be a better place for such a tool so we can standardize the output and expectations.
I recall that kubebuilder had something similar at one point in v1 but that no longer seems to be the case for v2. https://github.com/kubernetes-sigs/kubebuilder/issues/824#issuecomment-507404827
I wanted to check if there are any objections to adding this in controller-tools before I submit the initial PR. Or if this feature is already planned.
And also if we want to change the expected output format from what the prometheus-operator utility currently generates.
For starters, I imagine we can probably parse the validation tag comments and document that as well:
| Field | Description | Scheme | Required |
|---|
/cc @mengqiy Hoping to get the kubebuilder perspective on this. I might be wrong but I believe this is no longer included in kubebuilder v2 and I think this might be a better place for it.
kubebuilder v2 doesn't support docs command. It'd be great if we can bring it back.
Regarding the format, are there other format options here?
@mengqiy There is also the gen-crd-api-reference-docs tool which more closely follows the format of Kubernetes API reference docs: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/ Knative API docs example generated from that tool: https://knative.dev/docs/reference/
The table format is quite similar to the prometheus docs with just a:
| Field | Description |
|---|
with links to all the CRD types and upstream k8s types.
I'm having some trouble testing it out so I don't know if it generates markdown as well as html docs. Although my first thought was just starting with markdown and then maybe adding support for generating html docs as well.
Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale
@DirectXMan12: This request has been marked as needing help from a contributor.
Please ensure the request meets the requirements listed here.
If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.
In response to this:
/help
but you'll need to put together a proposal first
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.
Prometheus-operator documentation generation is markdown-focused and has some limitations, especially around formatting lists and code block examples for fields.
Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale
/lifecycle frozen
I think we still want this. But I need to throw together a proposal first if someone else doesn't.
Hey folks! I am the maintainer of https://doc.crds.dev and was chatting with @vincepri recently and was pointed to this issue. I would love to contribute the backend generation code (likely actually just rewrite it to fit better here) so folks can generate CRD documentation. I would also like to add in a small webserver that folks can run locally (similar to godoc) to view their documentation. Having controller-tools as the standard way to generate documentation should facilitate the ability to add common features and explore potential plugins that many projects already using controller-tools can take advantage of.
If this sounds like a good plan to the maintainers, I would like to get started right away on the doc generation, then follow it up with the local server implementation.
/assign /cc @vincepri @DirectXMan12
Super +1 on the plan described above, it'd be great to have these documentation bits as part of controller-tools
FWIW we developed a small tool to generate markdown from the CRD YAMLs: https://github.com/mesh-for-data/crdoc. Not as fancy as doc.crds.dev but works well for us as we use hugo and mkdocs to render our overall docs.
Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale