https://github.com/g4s8/envdoc
Go tool to generate documentation for environment variables
https://github.com/g4s8/envdoc
devtools documentation go go-generate
Last synced: 4 months ago
JSON representation
Go tool to generate documentation for environment variables
- Host: GitHub
- URL: https://github.com/g4s8/envdoc
- Owner: g4s8
- License: mit
- Created: 2023-12-11T08:05:25.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2025-07-08T18:31:32.000Z (5 months ago)
- Last Synced: 2025-07-08T19:40:03.500Z (5 months ago)
- Topics: devtools, documentation, go, go-generate
- Language: Go
- Homepage:
- Size: 276 KB
- Stars: 86
- Watchers: 3
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-go - envdoc - generate documentation for environment variables from Go source files. (Go Generate Tools / Routers)
- awesome-go-cn - envdoc
- awesome-go-plus - envdoc - generate documentation for environment variables from Go source files.  (Go Generate Tools / Routers)
- awesome-go-with-stars - envdoc - generate documentation for environment variables from Go source files. (Go Generate Tools / Routers)
- awesome-go - g4s8/envdoc
- awesome-go - envdoc - generate documentation for environment variables from Go source files. (Go Generate Tools / Routers)
- awesome-go - envdoc - generate documentation for environment variables from Go source files. (Go Generate Tools / Routers)
- fucking-awesome-go - envdoc - generate documentation for environment variables from Go source files. (Go Generate Tools / Routers)
- awesome-go-cn - envdoc
- awesome-go - envdoc - generate documentation for environment variables from Go source files. (Go Generate Tools / Routers)
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.
For `docenv` linter see [docenv/README.md](./docenv/README.md).
[](https://github.com/g4s8/envdoc/actions/workflows/go.yml)
[](https://pkg.go.dev/github.com/g4s8/envdoc)
[](https://codecov.io/gh/g4s8/envdoc)
[](https://goreportcard.com/report/github.com/g4s8/envdoc)
[](https://github.com/avelino/awesome-go)
## Installation
### Go >= 1.24
Add `envdoc` tool and install it:
```bash
go get -tool github.com/g4s8/envdoc@latest
go install tool
```
Add `go:generate`:
```go
//go:generate envdoc -output config.md
type Config struct {
// ...
}
```
Generate:
```bash
go generate ./...
```
### Before Go 1.24
Run it with `go run` in source file:
```go
//go:generate go run github.com/g4s8/envdoc@latest -output environments.md
type Config struct {
// ...
}
```
Or download binary to run it:
```bash
go install github.com/g4s8/envdoc@latest
```
And use it in code:
```go
//go:generate envdoc -output environments.md
type Config struct {
// ...
}
```
## Usage
```go
//go:generate envdoc -output
```
* `-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.
* `-target` (`enum(caarlos0, cleanenv)` string, optional, default `caarlos0`) - Set env library target.
* `-output` (path string, **required**) - Output file name for generated documentation.
* `-format` (`enum(markdown, plaintext, html, dotenv, json)` 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.
* `-tag-name` (string, *optional*, default: `env`) - Use custom tag name instead of `env`.
* `-tag-default` (string, *optional*, default: `envDefault`) - Use "default" tag name instead of `envDefault`.
* `-required-if-no-def` (bool, *optional*, default: `false`) - Set attributes as required if no default value is set.
* `-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`:
```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:
```md
# Environment Variables
- `PORT` (**required**) - Port to listen for incoming connections
- `ADDRESS` (default: `localhost`) - Address to serve
```
See [_examples](./_examples/) dir for more details.
## Compatibility
This tool is compatible with
- full compatibility: [caarlos0/env](https://github.com/caarlos0/env)
- full compatibility: [ilyakaznacheev/cleanenv](https://github.com/ilyakaznacheev/cleanenv)
- partial compatibility: [sethvargo/go-envconfig](https://github.com/sethvargo/go-envconfig)
- partial compatibility: [joeshaw/envdecode](https://github.com/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](/LICENSE.md) file for details.