https://github.com/evensolberg/tfdoc
Generates Terraform module documentation
https://github.com/evensolberg/tfdoc
autogenerated documentation terraform
Last synced: 4 months ago
JSON representation
Generates Terraform module documentation
- Host: GitHub
- URL: https://github.com/evensolberg/tfdoc
- Owner: evensolberg
- License: apache-2.0
- Created: 2023-01-20T20:02:07.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-02-09T11:26:46.000Z (5 months ago)
- Last Synced: 2026-02-09T16:25:23.362Z (5 months ago)
- Topics: autogenerated, documentation, terraform
- Language: HCL
- Homepage:
- Size: 293 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# tfdoc
This project aims at generating Terraform module documentation.
`tfdoc` will parse all the `.tf` files within a module's directory and generate markdown code blocks for each resource, data, variable and output block.
It will also include any comments that are placed directly above the block.
> **_NOTE: If no output options are specified, the application will still process the files, but will not produce any output._**
## Installation
You can build the executable yourself with [Rust](https://rust-lang.org).
```sh
# Installing Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Building the application from the repository directory:
cargo build --release
# Alternatively, you can install the application directly:
cargo install --path .
```
The Releases section of this repository also contains binary builds for various platforms.
## Usage
```sh
$ tfdoc [OPTIONS]
Arguments:
[DIR(S)] The directories to process. [default: .]
Options:
-l, --list [] Output the results as lists in a Markdown file. Default file name: tfdoc_summary_lists.md
-t, --table [] Output the results as tables in a Markdown file. Default file name: tfdoc_summary_tables.md
-c, --csv [] Output to a CSV file with the name provided. Default file name: tfdoc_summary.csv
-q, --quiet Suppress output and silently proceess inputs
-r, --recurse Recursively process directories
-h, --help Print help (see more with '--help')
-V, --version Print version
```
|Option|Description|
|------|-----------|
|`-c `, `--csv `|Export the results as a CSV file. Default file name if none is supplied: `tfdoc_summary.csv`|
|`-l `, `--table `|Export the results as a set of markdown lists into the file supplied. Default file name if none is supplied: `tfdoc_summary_lists.md`|
|`-t `, `--table `|Export the results as a set of markdown tables into the file supplied. Default file name if none is supplied: `tfdoc_summary_tables.md`|
|`-q`, `--quiet`|Do not produce any output other than error messages if something goes wrong.|
|`-r`, `--recurse`|Recursively process directories below the one specified.|
|`-h`, `--help`|Prints help in short form with `-h` and long form with `--help`|
|`-V`, `--version`|Prints version information|
You can specify multiple target directories like this:
```sh
tfdoc tests/simple tests/test-fixtures
```
## Expected Terraform File Formatting
The application will only process files with the `.tf` extension. It will ignore all other files.
If you wish to include a header for the file, you can do so by adding a comment at the top of the file. The comment must start with `# Title:` or `// Title:` and must be followed by a space. The comment can be followed by any text you wish to include:
```hcl
# Title: The name of the module
# Top comment prefixed by "Title: " and the following lines
# will be at the top of the Markdown file
```
Any resources, data, variables and output can also be documented using comments. The comment must start with `#` or `//` and must be followed by a space. The comment can be followed by any text you wish to include:
```hcl
# tfdoc keeps comments right on top of resource,
# variable, and output blocks.
resource "aws_instance" "this" {
# stuff
}
```
If you include a `description` within an element, this will also be processed:
```hcl
// We can have both comments on top
output "name" {
description = "and within outputs and variables"
}
```
Orphaned (i.e., not associated with a resource, data, variable or output) comments will be ignored.
## Troubleshooting
You can export some logging information by setting the `TFDOC_LOG` environment variable to one of `trace`, `debug`, `info`, `warn`, `error`. If nothing is specified, the application assumes `info`. Currently, only `debug` and `trace` will produce any additional output.
### Logging Examples
Starting the application with the environment variable specified can be done like this:
- `TFDOC_LOG=debug tfdoc .`
- `TFDOC_LOG=trace tfdoc test/simple/ -t -c result.csv`
Note that setting the logging level to `trace` may produce a lot of output.
## Acknowledgements
- This builds on the original [`tfdoc`](https://github.com/maur1th/tfdoc) by [Thomas Maurin](https://github.com/maur1th)