doc command

[adamdecaf]

Going further than #64 it's annoying to read the k8s.libsonnet file. I'd like to have something like the following:

$ k8s doc -f ../lib/k8s.libsonnet core.v1.container 
container(name string, image string)
  // Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
  withArgs(args []string)
  withArgs(args string)
  
  // Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
  withCommand(command []string)
  withCommand(command string)
...

Perhaps the doc comments could be shortened or excluded unless you drilled down on that specific method.

$ k8s doc -f ../lib/k8s.libsonnet core.v1.container.withArgs
// Arguments to the entrypoint. The docker image's CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container's environment. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VAR_NAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell

withArgs(args []string)
withArgs(args string)

[bryanl]

This idea looks interesting. I'm going to take a couple of days to play around with it and see what comes out.

[bryanl]

I have a preview of what ksonnet-lib documentation could look like up at http://g.bryan.dev.hepti.center.

[adamdecaf]

@bryanl That looks pretty awesome! It's much nicer to read than the raw jsonnet.

I noticed a couple things.

1. When you jump to each group the name of that group is cut off. Probably from the "ksonnet API Documentation" header taking up a few pixels ontop of the name.
2. I might change the (chevron?) icon here. I initially thought I could expand that. ¶ maybe?

http://g.bryan.dev.hepti.center/core/v1/binding/#core.v1.binding.metadata

[bryanl]

@adamdecaf this site is not the final layout. The experiment was to see if suitable documentation could be generated from k8s.libsonnet. It helped expose a few gaps which we can hopefully share with the k8s docs team to help improve downstream efforts. Thanks for taking a look and I will work on getting those fixes in there to make it easier to read.

[Quentin-M]

Hi there!

Is there any progress on this?

Using ksonnet / ksonnet-lib without documentation and with essentially no code completion (the vscode extension is meant to be used for ksonnet as a whole, not ksonnet-lib specifically - and completion freezes often) is hard, and is making several of our developers upset.

[ukclivecox]

Just a ping as I'm also finding it hard to write more complex ksonnet lib files where I need to understand the mixins and other method available.