Generating documentation from Terraform and OpenTofu sources

build.gradle

tfdocs {
  toolchains {
    standard { (1)
      executableByVersion('1.8.8') (2)
      executableByPath('/here/is/my/installed/terraform-docs') (3)
      executableBySearchPath('terraform-docs') (4)
    }
    myToolchain { (5)

    }
  }
}

1	Configures the provided toolchain called `standard`.
2	Use a specific version. If it is not available locally, then Gradle will bootstrap and cache it.
3	Use a fixed location of the executable.
4	Looks in the system search path for an executable called `terraform-docs` (or `terraform-docs.exe` on Windows).
5	Creates a new toolchain called `myToolchain`.

Publications

Publications are managed in tfdocs.docSets. Each documentation set is associated with a source folder of Terraform or OpenTofu source. This can be a source set or a module. This directory needs to be specified. At least one output type must be specified to produce some output. Every output type will result in a separate task. Output is normally produced in a folder of format build/docs/tf/DOCSET_NAME/OUTPUT_TYPE.

tfdocs {
  docSets {
    myPub { (1)
      sourceDir = '/path/to/srcdir' (2)
      sourceDir = terraform.sourceSets.named('foo') (3)
      sourceDir = terraform.modules.named('bar') (4)

      useToolchain('myToolchain') (5)

      outputs { (6)

      }
    }
  }
}

1	Declare a documentation set called `myPub`.
2	Declare a source directory using a path. This is lazy-evaluated and be anything convertible to a directory.
3	Declare a Terraform source set by name. Only if the appropriate Terraform (or OpenTofu) plugin is applied.
4	Similarly, a module can be declared as a source directory.
5	Use a toolchain other than the `standard` one.
6	Manages the outputs of the publication.

Publication outputs

Declaring an output

import org.ysb33r.gradle.tfdocs.outputs.Asciidoc

tfdocs {
  docSets {
    myPub {
      outputs {
        example(Asciidoc) { (1)

        }
      }
    }
  }
}

1	Registers an Asciidoc output. Will generate `build/docs/tf/myPub/asciidoc/example.adoc` by default. See below how to configure AsciiDoc and other output formats. It will also register a task called `tfdocMyPubExample`.

Common output configuration

All outputs can be configured with the following parameters

tfdocs {
  docSets {
    myPub {
      defaultConfig { (1)
        header = 'head.tf' (2)
        footer = 'somefile.md' (3)
        outputTemplate = '<!-- BEGIN_TF_DOCS -->\n{{ .Content }}\n<!-- END_TF_DOCS -->' (4)
        readLockfile = true (5)
        readComments = true (6)
        includeSubModules = true (7)
        subModulePath = 'mod00les' (8)
        hideAllSections = false (9)
        hideDataSources = false (10)
        hideHeader = false (11)
        hideFooter = false (12)
        hideInputs = false (13)
        hideModules = false (14)
        hideOutputs = false (15)
        hideProviders = false (16)
        hideRequirements = false (17)
        hideResources = false (18)

        sortByName()  (19)
        sortByType()  (20)
        sortByRequired()  (21)
      }
      outputs {
        example(Asciidoc) {
          hideResources = true (22)
        }
      }
    }
  }
}

1	Configurations that by default are applied to all outputs.
2	Set a custom header. This must be relative to the module or source set. Lazy-evaluated. Can be set by a provider.
3	Set a custom footer. This must be relative to the module or source set. Lazy-evaluated. Can be set by a provider.
4	Override the default custom template. Lazy-evaluated. Can be set by a provider.
5	Reads the `.terraform.lock.hcl` if it exists.
6	Whether to use comments as description when the description is empty.
7	Whether to recursively process submodules.
8	In which subdirectory, the submodules are to be found. Default is `modules`. Ignored if `includeSubModules` is false. Lazy-evaluated. Can be set by a provider.
9	Whether all sections should be hidden.
10	Whether data sources should be hidden.
11	Whether the header should be hidden.
12	Whether the footer should be hidden.
13	Whether inputs should be hidden.
14	Whether submodules should be hidden.
15	Whether outputs should be hidden.
16	Whether providers should be hidden.
17	Whether requirements should be hidden.
18	Whether resources should be hidden.
19	Sets the sort mode to `name`.
20	Sets the sort mode to `type`.
21	Sets the sort mode such that required items are listed first.
22	Override a configuration for a specific output format

Supported output types

Asciidoc
Json
Markdown
Pretty
TfVars
Toml
Yaml
Xml

Configuring Asciidoc output

Configuring specific options

import org.ysb33r.gradle.tfdocs.outputs.Asciidoc (1)

tfdocs {
  docSets {
    myPub {
      outputs {
        example(Asciidoc) {
            useTableMode() (2)
            useDocumentMode() (3)

            anchorLinks = true (4)
            showDefault true (5)
            showRequired = true (6)
            showSensitive = true (7)
            showType = true (8)
            hideEmptySections = false (9)
            indent = 2 (10)
        }
      }
    }
  }
}

1	Import the output class.
2	Use a table to place inputs and outputs.
3	Use a document flow to place inputs and outputs.
4	Create anchor links. Default is `true`.
5	Show the `Default` section or column. Default is `true`.
6	Show the `Required` section or column. Default is `true`.
7	Show the `Sensitive` section or column. Default is `true`.
8	Show the `Type` section or column. Default is `true`.
9	Hide empty sections. Default is `false`.
10	Indentation level for sections. Must be in the range 1–5. Default is 2.

Configuring JSON output

Configuring specific options

import org.ysb33r.gradle.tfdocs.outputs.Json (1)

tfdocs {
  docSets {
    myPub {
      outputs {
        example(Json) {
          escapeSpecialCharacters = true (2)
        }
      }
    }
  }
}

1	Import the output class.
2	Escape special characters. The default is `true`.

Configuring Markdown output

Configuring specific options

import org.ysb33r.gradle.tfdocs.outputs.Markdown (1)

tfdocs {
  docSets {
    myPub {
      outputs {
        example(Markdown) {
            useTableMode() (2)
            useDocumentMode() (3)

            anchorLinks = true (4)
            showDefault true (5)
            showRequired = true (6)
            showSensitive = true (7)
            showType = true (8)
            hideEmptySections = false (9)
            indent = 2 (10)

            useHtmlTags = true (11)
            escapeSpecialCharacters = true (12)
        }
      }
    }
  }
}

1	Import the output class.
2	Use a table to place inputs and outputs.
3	Use a document flow to place inputs and outputs.
4	Create anchor links. Default is `true`.
5	Show the `Default` section or column. Default is `true`.
6	Show the `Required` section or column. Default is `true`.
7	Show the `Sensitive` section or column. Default is `true`.
8	Show the `Type` section or column. Default is `true`.
9	Hide empty sections. Default is `false`.
10	Indentation level for sections. Must be in the range 1–5. Default is 2.
11	Use HTML tags in generated output. Default is `true`.
12	Escape special characters. Default is `true`.

Configuring TfVars output.

Configuring specific options

import org.ysb33r.gradle.tfdocs.outputs.TfVars (1)

tfdocs {
  docSets {
    myPub {
      outputs {
        example(TfVars) {
           useJsonOutput() (2)
           useHclOutput() (3)
           descriptions = true (4)
        }
      }
    }
  }
}

1	Import the output class.
2	Outputs to JSON.
3	Outputs to HCL. This is the default mode.
4	Show descriptions on variables in HCL mode.

Generating all documentation

Use the tfdocAll task to run all of the documentation generation tasks.