conduit-docs

conduit-docs is a utility used to generate markdown files from Conduit plugin config structs.
It's usage is designed around //go:generate, which should be run on each plugin's *.go config file.

File Names

The output file name will be the go package name suffixed with .md

To override the output filename, use a comment beginning with //Name: The remaining portion of the comment will be suffixed with .md and used as the file name.

Converting structs to graphs

The structs within the file will be turned into a graph listing the yaml key, the type of the entry, and using the comment above each field as a description.

For example,

package example 

//go:generate go run ../../../../cmd/conduit-docs/main.go ../../../../conduit-docs/

type Config struct {
	// description field of the graph
	Field string `yaml:"field-name"`
}

will output the following graph:

key	type	description
field-name	string	description field of the graph

Additional data in header/footer

In addition to converting structs to documentation graphs, you can add additional markdown to the top and bottom of the output document via comments denoted with certain values.

A multi-line comment beginning with /*Header will be added to the beginning of the document.

And a multi-line comment beginning with /*Footer will be added to the end of the document.

So the following config,

package example 

//go:generate go run ../../../../cmd/conduit-docs/main.go ../../../../conduit-docs/

/*Header
## Config Documentation
This is a config which is being documented.
 */

type Config struct {
	// description field of the graph
	Field string `yaml:"field-name"`
}
/*Footer
## Examples
These are some examples  
`Foo=bar`
 */

will output the following document:

Config Documentation

This is a config which is being documented.

key	type	description
field-name	string	description field of the graph

Examples

These are some examples
Foo=bar