tf_docs

README

tf_docs

Parses Terraform modules extracting useful information to use as documentation

Usage

modules, err := tf.ParseModules("path/to/my/modules")

How it Works

Description

Looks for a comment on line 1 of a .tf file that starts with the module name (directory name):

# moduleName does this...
# also does this

\* moduleName does a bunch of things
*\

Variables

Takes the variable name, type and description. If the default is present then extracted too. A required field is calculated based on whether a default is available.

variable "name" {
  type        = "type"
  description = "description"
  default     = "default" # optional
}

Outputs

The name and description of outputs are extracted

output "name" {
  description = "description"
  value       = "value"
}

Modules and Resources

Leading comments (on the line preceding the declaration of the module/resource) are used as descriptions.

// describe this resource
resource "type" "name" {
   ...
}

Resources

The type and name of the resource are extracted.

resource "name" "type {
  ...
}

Modules

The name and source of the modules are extracted.

module "name" {
  source = "source"
}

Documentation

Index

• Constants
• func ListModuleFiles(directory string) ([]string, error)
• type Comment
• type Module
• type Output
• type Resource
• type TFModule
  • func FindAndParse(directory string) ([]*TFModule, error)
  • func Parse(hclText []string, moduleName string) (*TFModule, error)
• type Value
• type Variable

Constants

const (
	VARIABLE = "variable"
	OUTPUT   = "output"
	MODULE   = "module"
	RESOURCE = "resource"
)

Functions

func ListModuleFiles

func ListModuleFiles(directory string) ([]string, error)

listModuleFiles returns a list ouf files with a .tf extension within a directory.

Types

type Comment

type Comment struct {
	Text string
	Col  int
	Line int
}

type Module

type Module struct {
	Name        string
	Description string
	Source      string
}

type Output

type Output struct {
	Description string
	Name        string
}

type Resource

type Resource struct {
	Type        string
	Name        string
	Description string
}

type TFModule

type TFModule struct {
	Path        string
	Title       string
	Link        string
	Variables   []*Variable
	Outputs     []*Output
	Resources   []*Resource
	Modules     []*Module
	Description string
}

func FindAndParse

func FindAndParse(directory string) ([]*TFModule, error)

FindAndParse finds all of the modules within a directory and parses them all.

func Parse

func Parse(hclText []string, moduleName string) (*TFModule, error)

Parse generates a TFModule given a number of Terraform files (as strings) as input

type Value

type Value struct {
	Key     map[string][]string
	Val     map[string]string
	Comment Comment
}

type Variable

type Variable struct {
	Name        string
	Type        string
	Description string
	Default     string
	Required    bool
}