📚 envdoc - Awesome Go Library for Go Generate Tools
generate documentation for environment variables from Go source files.
Detailed Description of envdoc
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>
-dir
(path string, optional) - Specify the directory to search for files. Default is the file dir withgo:generate
command.-files
(glob string, optional) - File glob pattern to specify file names to process. Default is the single file withgo:generate
.-types
(glob string, optional) - Type glob pattern for type names to process. If not specified, the next type aftergo: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 ismarkdown
.-no-styles
(bool
, optional) - If true, CSS styles will not be included forhtml
format.-env-prefix
(string
, optional) - Sets additional global prefix for all environment variables.-field-names
(bool
, optional) - Use field names as env names ifenv:
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
- 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.