We could introduce kind as a rest resource, which also function as component plugin, with links to the swagger operations (or embedded them).

May not be any value to the indirection, except it could solve both problems at the same time. Let me noodle it a bit.

On Dec 19, 2014, at 1:06 PM, bgrant0607 notifications@github.com wrote:

Now that we have the swagger API, it would be useful to be able to query it and select parts to display, as part of help in kubectl.

Maybe something like:

kubectl describekind pod
kubectl describeop get pods
/cc @smarterclayton @nikhiljindal @ghodss

—
Reply to this email directly or view it on GitHub.

maybe this can also be included in #5275

@xudifsd Yes, definitely. We just need to agree on the kubectl syntax, and it can target the existing swagger api. Changes to apiserver (kind resource, plugins, etc.) can be resolved later.

@smarterclayton Did you noodle this at all?

How about:

kubectl describe resource /pods

which would display the swagger for the operations on /api/<version>/namespaces/<namespace>/pods (using defaults for namespace and version, unless otherwise specified in the usual way).

and

kubectl describe kind Pod

which would display the swagger for the schema for <version>.Pod and subobjects (using the default version, unless specified in the usual way).

I could also imagine supporting jsonpath syntax to ask for the info for a specific field.

Absolutely want this. I want a "list resources" with nice descriptions, then a describe that shows the data.

Maybe we want to use "types"?

On Mar 11, 2015, at 12:27 PM, Brian Grant notifications@github.com wrote:

@xudifsd Yes, definitely. We just need to agree on the kubectl syntax, and it can target the existing swagger api. Changes to apiserver (kind resource, plugins, etc.) can be resolved later.

@smarterclayton Did you noodle this at all?

How about:

kubectl describe resource /pods
which would display the swagger for the operations on /api//namespaces//pods (using defaults for namespace and version, unless otherwise specified in the usual way).

and

kubectl describe kind Pod
which would display the swagger for the schema for .Pod and subobjects (using the default version, unless specified in the usual way).

I could also imagine supporting jsonpath syntax to ask for the info for a specific field.

—
Reply to this email directly or view it on GitHub.

Also we really want to be able to put long descriptions on types themselves (paragraph long form even) and have that show up in swagger.

On Mar 11, 2015, at 12:27 PM, Brian Grant notifications@github.com wrote:

@xudifsd Yes, definitely. We just need to agree on the kubectl syntax, and it can target the existing swagger api. Changes to apiserver (kind resource, plugins, etc.) can be resolved later.

@smarterclayton Did you noodle this at all?

How about:

kubectl describe resource /pods
which would display the swagger for the operations on /api//namespaces//pods (using defaults for namespace and version, unless otherwise specified in the usual way).

and

kubectl describe kind Pod
which would display the swagger for the schema for .Pod and subobjects (using the default version, unless specified in the usual way).

I could also imagine supporting jsonpath syntax to ask for the info for a specific field.

—
Reply to this email directly or view it on GitHub.

Filed #5331 re. documentation on types themselves.

Hello I would like to submit a GSoC proposal for this subject. I believe that UX through documentation is very important especially in large and complex project like Kubernetes (even though that this issues is a P3).

I have seen that there is a general kubectl roadmap and I am also aware that there is an other student that applies for improving #5275. I think that the roadmap is quite large for just one person to work all the issues, and maybe two students can split them equally to also increase the quality.

Do you think that something like this would be acceptable?

@andronat Thanks for your interest! I agree that the full roadmap is a lot of work. I'm not sure this issue is enough work on its own for a whole project, but I'll take a look at your proposal and provide feedback there.

BTW, the prioritization doesn't imply that this is unimportant, only that we have lots of other issues that are even more important/urgent. :-)

This came up in friction study -- people didn't want to read docs. Some help in kubectl to explain the main concepts would help.

Here's the start of this for OpenShift openshift/origin#2914

I went for the straight simple approach for now - displaying a list of concrete paragraphs for each concept. Ultimately I think these are descriptions that should be present in the swagger doc (although for swagger there may be more paragraphs per resource, and certain concepts like Labels will have to live somewhere else). I'd also like to do searching and linux PAGER integration but that will wait for us.

cc @caesarxuchao

@bgrant0607 I am working on it and I'll report progress really soon

This is exciting. Once kubectl can emit this, then one of us can make a gendocs that generates static docs from the kubectl output.

@erictune Clayton is working on generating markdown from swagger spec: #9097

The PR for this feature is at #12677.

PR #12677 has been merged. I think this can be closed.