Autogenerate reference documentation

[pradeepto]

How can this be done? Is there anything we can steal from kubernetes? Is there a golang way of generating documentation from code like Python docstrings? Can we use godoc?

[tnozicka]

This would be great for long term as it will ensure the file reference format is always up to date.

Is there anything we can steal from kubernetes?

Not sure about any solution we could use from k8s. They have it easier because their API is described by swagger/protobuf. We don't have such API. Our parser is defined by the parsing code and structures.

Is there a golang way of generating documentation from code like Python docstrings? Can we use godoc?

Not the case. This documents the code, not the parser. It needs special interpretation and transformation to generate something like https://github.com/redhat-developer/opencompose/blob/master/docs/file-reference.md

On a really quick look I can see 2 ways how to achieve it:

1. using reflection on parser structs and StructTags

• Easier, but we would be kind of limited with the lack of additional info

2. by writing a tool to parse Golang AST w.r.t. parser structs

• More advanced and we could parse the Golang comments as well and interpret them in a special way. This would give us greater flexibility. Golang parsing seems to be a part of standard library https://golang.org/pkg/go/

With that said, there are more pressing issues at hand.