Generate reference documentation in the book

randomvariable commented 3 years ago

User Story

As a user, I want to read the API spec of Cluster API without having to deploy it and use kubectl explain

Detailed Description

Upstream the CRD and CLI reference doc generation from CAPA

CRD output: https://cluster-api-aws.sigs.k8s.io/crd/cluster-api-aws.html

CLI output: https://cluster-api-aws.sigs.k8s.io/clusterawsadm/clusterawsadm.html

Generation code is: CLI doc generator: https://github.com/kubernetes-sigs/cluster-api-provider-aws/tree/master/docs/book/cmd/clusterawsadmdocs

The Makefile contains the following: CRD doc generation Bit of hackery to assemble a SUMMARY.md (mdbook won't run plugins on the sidebar by design, so you have to construct it): https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/master/docs/book/Makefile

Anything else you would like to add:

[Miscellaneous information that will assist in solving the issue.]

/kind documentation

detiber commented 3 years ago

I'm wondering if we can leverage https://doc.crds.dev/ here in some way?

randomvariable commented 3 years ago

I used the one I did as it's used in knative. The CAPA ones do actually currently link out to docs.crds.dev for the CAPI CRDs at the moment. Didn't see a neat way to output a file in a way that mdbook would render it with the latter.

vincepri commented 3 years ago

I'm wondering if we can leverage https://doc.crds.dev/ here in some way?

I was chatting with @hasheddan a while back about this, we ended up in https://github.com/kubernetes-sigs/controller-tools/issues/240 which would be great to integrate with.

randomvariable commented 3 years ago

Very cool.

Maybe I can do the CLI reference docs first then?

hasheddan commented 3 years ago

@randomvariable @vincepri I am planning on ramping up on https://github.com/kubernetes-sigs/controller-tools/issues/240 very soon and will try to get this usable for y'all ASAP :)

vincepri commented 3 years ago

/milestone Next

k8s-triage-robot commented 3 years ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue or PR as fresh with /remove-lifecycle stale
Mark this issue or PR as rotten with /lifecycle rotten
Close this issue or PR with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue or PR as fresh with /remove-lifecycle rotten
Close this issue or PR with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

sbueringer commented 2 years ago

Would it make sense to add to a link to https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api in our book in the meantime?

randomvariable commented 2 years ago

Yes. I do point users at CRD docs sometimes.

vincepri commented 2 years ago

I wonder if we can embed those references?

hasheddan commented 2 years ago

Apologies for the delay on https://github.com/kubernetes-sigs/controller-tools/issues/240 folks. @vincepri are you thinking something along the lines of an iframe embed? Happy to update https://doc.crds.dev to accommodate any use-case y'all need :)

vincepri commented 2 years ago

Something like that? We could also embed the html directly, but have no idea if that's actually going to work

randomvariable commented 2 years ago

Coming back to this, would be good to get this in, as per CII best practices, which I'm reviewing for the security self assessment:

The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. [documentation_interface]

The documentation of an external interface explains to an end-user or developer how to use it. This would include its application program interface (API) if the software has one. If it is a library, document the major classes/types and methods/functions that can be called. If it is a web application, define its URL interface (often its REST interface). If it is a command-line interface, document the parameters and options it supports. In many cases it's best if most of this documentation is automatically generated, so that this documentation stays synchronized with the software as it changes, but this isn't required. The project MAY use hypertext links to non-project material as documentation. Documentation MAY be automatically generated (where practical this is often the best way to do so). Documentation of a REST interface may be generated using Swagger/OpenAPI. Code interface documentation MAY be generated using tools such as JSDoc (JavaScript), ESDoc (JavaScript), pydoc (Python), devtools (R), pkgdown (R), and Doxygen (many). Merely having comments in implementation code is not sufficient to satisfy this criterion; there needs to be an easy way to see the information without reading through all the source code. If the project does not produce software, choose "not applicable" (N/A). .

sbueringer commented 2 years ago

Including a direct link to https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api in the sidebar would be a quick win. Embedding it in an iframe which also looks good via mdbook isn't (at least not for me)

randomvariable commented 2 years ago

Yup, I think that'll suffice tbh.

sbueringer commented 2 years ago

Note: It's not a quick win to add it to the sidebar as mdbook doesn't allow external links there. It would be a quick-win to add a page which only contains a link :/

randomvariable commented 2 years ago

Oh yeah, I'm doing some dodgy stuff with the sidebar in the CAPA repo.

randomvariable commented 2 years ago

I've figured out a solution that doesn't involve running gen-crd-api-reference-docs that is super slow and doesn't support go modules, which is essentially to read the openapi specs from the YAML and construct a OpenAPI v3 doc which you can display with some OSS JavaScript. I'll PR soon.

randomvariable commented 2 years ago

/assign

randomvariable commented 2 years ago

Example here https://deploy-preview-2883--kubernetes-sigs-cluster-api-provider-aws.netlify.app/crd/#get-/apis/bootstrap.cluster.x-k8s.io/v1alpha3/eksconfigtemplates

https://github.com/kubernetes-sigs/cluster-api-provider-aws/pull/2883

randomvariable commented 2 years ago

/lifecycle active

k8s-triage-robot commented 2 years ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue or PR as fresh with /remove-lifecycle stale
Mark this issue or PR as rotten with /lifecycle rotten
Close this issue or PR with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

sbueringer commented 2 years ago

/remove-lifecycle stale

I think we still want to address this in some way.

kubernetes-sigs / cluster-api

Generate reference documentation in the book #4484