envdoc

README

envdoc

envdoc is a tool for generating documentation for environment variables in Go structs. It takes comments associated with env tags in Go structs and creates a Markdown, plaintext or HTML file with detailed documentation.

Installation

Run it with go run in source file:

//go:generate go run github.com/g4s8/envdoc@latest -output environments.md -type Config
type Config struct {
    // ...
}

Or download binary to run it:

go install github.com/g4s8/envdoc@latest

And use it in code:

//go:generate envdoc -output environments.md
type Config struct {
    // ...
}

Usage

//go:generate envdoc -output <output_file_name> -type <target_type_name> 

• -output (required) - Specify the output file name for the generated documentation.
• -type: Specify the target struct type name to generate documentation for. If ommited, the next type after go:generate comment will be used.
• -format (default: markdown) - Set output format type, either markdown, plaintext, html, or dotenv.
• -all - Generate documentation for all types in the file.
• -env-prefix - Environment variable prefix.
• -no-styles - Disable built-int CSS styles for HTML format.
• -field-names - Use field names instead of struct tags for variable names if tags are not set.

Example

Suppose you have the following Go file config.go:

package foo

//go:generate envdoc --output env-doc.md
type Config struct {
  // Port to listen for incoming connections
  Port int `env:"PORT,required"`
  // Address to serve
  Address string `env:"ADDRESS" envDefault:"localhost"`
}

And the go:generate line above creates documentation in env-doc.md file:

# Environment Variables

- `PORT` (**required**) - Port to listen for incoming connections
- `ADDRESS` (default: `localhost`) - Address to serve

See _examples dir for more details.

Compatibility

This tool is compatible with

• full compatibility: caarlos0/env
• partial compatibility: sethvargo/go-envconfig
• partial compatibility: joeshaw/envdecode

Let me know about any new lib to check compatibility.

Contributing

If you find any issues or have suggestions for improvement, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Documentation

Overview

envdoc is a tool to generate documentation for environment variables from a Go source file. It is intended to be used as a go generate directive.

For example, given the following Go type with struct tags and a `go:generate` directive:

//go:generate go run github.com/g4s8/envdoc@latest -output config.md
type Config struct {
	// Host name to listen on.
	Host string `env:"HOST,required"`
	// Port to listen on.
	Port int `env:"PORT,notEmpty"`

	// Debug mode enabled.
	Debug bool `env:"DEBUG" envDefault:"false"`
}

Running go generate will generate the following Markdown file:

# Environment variables

- `HOST` (**required**) - Host name to listen on.
- `PORT` (**required**, not-empty) - Port to listen on.
- `DEBUG` (default: `false`) - Debug mode enabled.

By default envdoc generates documentation in Markdown format, but it can also generate plaintext or HTML.

Options:

• `-output` - Output file name.
• `-type` - Type name to generate documentation for. Defaults for the next type after `go:generate` directive.
• `-format` (default: `markdown`) - Set output format type, either `markdown`, `plaintext` or `html`.
• `-all` - Generate documentation for all types in the file.
• `-env-prefix` - Environment variable prefix.
• `-no-styles` - Disable built-int CSS styles for HTML format.
• `-field-names` - Use field names instead of struct tags for variable names if tags are not set.