search

kubernetes / kubectl

Issue tracker and mirror of kubectl code
Apache License 2.0
2.88k stars 922 forks source link

`kubectl explain -o md` #1419

Open kaovilai opened 1 year ago

kaovilai commented 1 year ago

What would you like to be added: Markdown documentation export from a CRD using kubectl explain <full-resource-name|kind|shortname> -o md And ideally it would accept -i /path/to/local/crd.yaml

Why is this needed: For auto generated documentation of an Custom Resource to markdown/html formats.

k8s-ci-robot commented 1 year ago

This issue is currently awaiting triage.

SIG CLI takes a lead on issue triage for this repo, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.
eddiezane commented 1 year ago

I think this work is possible now thanks to the OpenAPI v3 work done for explain.

https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/3515-kubectl-explain-openapiv3#markdown

@alexzielenski did you have any plans to work on this or are tracking it elsewhere?

alexzielenski commented 1 year ago

This is not being tracked in an issue anywhere but we discussed it as a possibility as part of the KEP: https://github.com/alexzielenski/enhancements/blob/8f93b2a2625eac939d3ea8ff3676819c9c5ccf75/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md#markdown

This was not included in the original implementation so we could receive feedback from users first to see if there is a desire for this. Also discussed in the KEP and in our initial meetings was a possible alternative to md output. First-party md output requires opinionated design choices which may not be useful for everybody. An openapiv3 output of the requested subschema could be fed into a user's templating engine of choice.

Link to KEP: https://github.com/alexzielenski/enhancements/blob/8f93b2a2625eac939d3ea8ff3676819c9c5ccf75/keps/sig-cli/3515-kubectl-explain-openapiv3/README.md#openapiv3-raw-json

openapiv3 output was included in the KEP but dropped during implementation to make sure we only introduce new command line options we know we need. It seems like it might work for you if we add it (small/low risk change already approved in KEP). What do you think?

kaovilai commented 1 year ago

+1 to whatever allows for export of docs. Perhaps --recursive so it generates for all nested fields as well.

k8s-triage-robot commented 10 months ago

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

This bot triages un-triaged issues according to the following rules:

You can:

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

/lifecycle stale

kaovilai commented 9 months ago

/remove-lifecycle stale

k8s-triage-robot commented 6 months ago

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

This bot triages un-triaged issues according to the following rules:

You can:

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

/lifecycle stale

kaovilai commented 6 months ago

unstale

nnzv commented 6 months ago

+1 to whatever allows for export of docs. Perhaps --recursive so it generates for all nested fields as well.

Sounds like a good plan!

Ritikaa96 commented 5 months ago

/remove-lifecycle stale

k8s-triage-robot commented 2 months ago

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

This bot triages un-triaged issues according to the following rules:

You can:

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

/lifecycle stale

kaovilai commented 2 months ago

/remove-lifecycle stale