Tool to generate API documentation in markdown

[hasbro17]

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

[hasbro17]

/cc @DirectXMan12 @droot

[hasbro17]

/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.

[mengqiy]

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?

[hasbro17]

@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.

[fejta-bot]

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]

/remove-lifecycle stale

[DirectXMan12]

/help

but you'll need to put together a proposal first

[k8s-ci-robot]

@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](https://github.com/kubernetes-sigs/controller-tools/issues/240): >/help > >but you'll need to put together a proposal first Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.

[vsliouniaev]

Prometheus-operator documentation generation is markdown-focused and has some limitations, especially around formatting lists and code block examples for fields.

[fejta-bot]

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

[hasbro17]

/lifecycle frozen

I think we still want this. But I need to throw together a proposal first if someone else doesn't.

[tamalsaha]

https://github.com/ahmetb/gen-crd-api-reference-docs

[hasheddan]

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

[hasheddan]

/remove-lifecycle frozen /remove help

[vincepri]

Super +1 on the plan described above, it'd be great to have these documentation bits as part of controller-tools

[roee88]

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.

[fejta-bot]

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

[vincepri]

/lifecycle frozen