TF-Docs

tfdocs lets you generate README.md for Terraform modules based on variables.tf. Additionally, it can sort variable definitions.

Usage

tfdocs [flags] <variables.tf>

Flags:

-h, --help            Show this help message and exit
--name, -n            Specify a custom name for the module
--readme              Specify the name of the output file (default: README.md)
--variables           Specify the name of the file containing variables (default: variables.tf)
--source SOURCE       Specify a custom source for the module
--git-source          Only to be used together with --source to specify the source is a git repository. If true, sub directory and a place holder TAG will be appended to the source
-f                    Format and sort variables.tf file
--dry-run             Show the output without writing to the file
--version

Input file

Default: variables.tf

All the input variables of the module must be defined in a single file. By default tfdocs will look for a file named variables.tf in the current directory. Alternatively a custom file can be specified using the --variables flag.

Example

variables.tf

variable "my_string" {
  type = string
  description = "Description of the string"
  default = "default"
}

variable "my_list" {
  type = List(string)
  description = "Description of the list"
  default = ["default"]
}

Format variables.tf

You can use the -f flag to format the variables.tf file. This will sort the variables in alphabetical order.

Generated Readme file

Default: README.md

The module expects to have a README.md file in the current directory. If the file does not exist, tfdocs will create one. Alternatively, a custom file can be specified using the --readme flag.

Example

README.md

# My module

Insert a description of the module here.

<!-- TFDOCS START -->
module <my_module> {
source = "git@github.com:<your_name>/<your_repo>.git//<subfolder>?ref=<TAG>"
my_list = <LIST(STRING)>    # Description of the list
my_string = <STRING>        # Description of the string
}
<!-- TFDOCS END -->

Custom content

tfdocs replaces only the content between the markers below with variable definitions from variables.tf.

Markers: <!-- TFDOCS START --> and <!-- TFDOCS END -->

Module Source

Default: git-remote-origin//<subfolder>?ref=<TAG>

By default, if the module is in a Git repository, tfdocs will utilize the remote origin to generate the source URL (git://github.com/<your_name>/<your_repo>.git//<subfolder>?ref=<TAG>).

Otherwise, either the source URL can be specified using the --source flag or if not provided it will default to ./modules/{CURRENT_DIRECTORY}.

Annotations

Override variable type

Use #tfdocs: type=<TYPE> to override the variable type. This is useful when the type is not correctly inferred from the variable definition or when you want to customize it.

Example

variables.tf

variable "my_object" {
  #tfdocs: type = list(object)
  type = list(object({
    name = string
    size = number
    directory = string
  }))
  description = "Description of the string"
  default = "default"
}

Note: tfdocs overwrite an existing README.md file. It's always good to use --dry-run first.

Authors

tfdocs is created and maintained by vajeen.