Skip to content
/ envdoc Public

Go tool to generate documentation for environment variables

License

Notifications You must be signed in to change notification settings

g4s8/envdoc

Repository files navigation

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.


CI Go Reference codecov Go Report Card Mentioned in Awesome Go

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>
  • -dir (path string, optional) - Specify the directory to search for files. Default is the file dir with go:generate command.
  • -files (glob string, optional) - File glob pattern to specify file names to process. Default is the single file with go:generate.
  • -types (glob string, optional) - Type glob pattern for type names to process. If not specified, the next type after go:generate is used.
  • -output (path string, required) - Output file name for generated documentation.
  • -format (enum(markdown, plaintext, html, dotenv) string, optional) - Output format for documentation. Default is markdown.
  • -no-styles (bool, optional) - If true, CSS styles will not be included for html format.
  • -env-prefix (string, optional) - Sets additional global prefix for all environment variables.
  • -field-names (bool, optional) - Use field names as env names if env: tag is not specified.
  • -debug (bool, optional) - Enable debug output.

These params are deprecated and will be removed in the next major release:

  • -type - Specify one type to process.
  • -all - Process all types in a file.

Both parameters could be replaced with -types param:

  • Use -types=Foo instead of -type=Foo.
  • Use -types='*' instead of -all.

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

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.