terraform-plugin-docs

module
v0.4.1-0...-2f1f684 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 7, 2021 License: MPL-2.0

README

terraform-plugin-docs

This repository contains tools and packages for creating Terraform plugin docs (currently only provider plugins). The primary way users will interact with this is the tfplugindocs CLI tool to generate and validate plugin documentation.

tfplugindocs

The tfplugindocs CLI has two main commands, validate and generate (generate is the default). This tool will let you generate documentation for your provider from live example .tf files and markdown templates. It will also export schema information from the provider (using terraform providers schema -json), and sync the schema with the reference documents. If your documentation only consists of simple examples and schema information, the tool can also generate missing template files to make website creation extremely simple for most providers.

How it Works

When you run tfplugindocs from root directory of the provider the tool takes the following actions:

  • Copy all the templates and static files to a temporary directory
  • Build (go build) a temporary binary of the provider source code
  • Collect schema information using terraform providers schema -json
  • Generate a default provider template file, if missing (index.md)
  • Generate resource template files, if missing
  • Generate data source template files, if missing
  • Copy all non-template files to the output website directory
  • Process all the remaining templates to generate files for the output website directory

You can see an example of the templates and output in paultyng/terraform-provider-unifi and browse the generated docs in the Terraform Registry.

Conventional Paths

The generation of missing documentation is based on a number of assumptions / conventional paths:

Path Description
templates/ Root of templated docs
templates/index.md[.tmpl] Docs index page (or template)
examples/provider/provider.tf Provider example config*
templates/data-sources.md[.tmpl] Generic data source page (or template)
templates/data-sources/<data source name>.md[.tmpl] Data source page (or template)
examples/data-sources/<data source name>/data-source.tf Data source example config*
templates/resources.md[.tmpl] Generic resource page (or template)
templates/resources/<resource name>.md[.tmpl] Resource page (or template)
examples/resources/<resource name>/resource.tf Resource example config*
examples/resources/<resource name>/import.sh Resource example import command
Templates

The templates are implemented with Go text/template using the following objects and functions:

Template Objects

TBD

Template Functions
Function Description
codefile Create a Markdown code block and populate it with the contents of a file. Path is relative to the repository root.
tffile A special case of the codefile function. In addition this will elide lines with an OMIT comment.
trimspace strings.TrimSpace
plainmarkdown Render Markdown content as plaintext
Installation

You can install a copy of the binary manually from the releases, or you can optionally use the tools.go model for tool installation.

Disclaimer

This experimental repository contains software which is still being developed and in the alpha testing stage. It is not ready for production use.

Directories

Path Synopsis
cmd
internal
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL