Skip to main content

Docs

Configure documentation generation for READMEs, release notes, and other artifacts. Define multiple named documentation generators that can be invoked via atmos docs generate <name>.

Configuration​

Documentation generation is configured in the docs.generate section:

atmos.yaml

docs:
  generate:
    readme:
      base-dir: .
      input:
        - "./README.yaml"
      template: "https://raw.githubusercontent.com/cloudposse/terraform-null-label/main/README.md.gotmpl"
      output: "./README.md"
      terraform:
        source: src/
        enabled: false
        format: "markdown"
        show_providers: false
        show_inputs: true
        show_outputs: true
        sort_by: "name"
        hide_empty: false
        indent_level: 2

    release-notes:
      base-dir: .
      input:
        - "./CHANGELOG.yaml"
      template: "./release-notes.gotmpl"
      output: "./RELEASE_NOTES.md"

Configuration Options​

Each named section under docs.generate supports the following options:

base-dir
Base directory for resolving relative paths. Defaults to current working directory.
input
List of YAML input files to combine. Supports local paths and remote URLs via go-getter.
template
Path or URL to the Go template file used to generate the output.
output
Path where the generated documentation will be written.
terraform
Optional terraform-docs configuration for including Terraform documentation in the output.

Terraform Documentation Options​

When terraform is configured, Atmos can include Terraform module documentation in your generated files:

terraform.source
Path to the Terraform module source directory.
terraform.enabled
Whether to generate Terraform documentation. Default: false.
terraform.format
Output format for Terraform docs. Options: markdown, markdown table, tfvars hcl, tfvars json. Default: markdown table.
terraform.show_providers
Include provider information in the output. Default: false.
terraform.show_inputs
Include input variables in the output. Default: true.
terraform.show_outputs
Include outputs in the output. Default: true.
terraform.sort_by
How to sort inputs/outputs. Options: name, required, type. Default: name.
terraform.hide_empty
Hide sections with no content. Default: false.
terraform.indent_level
Indentation level for nested content. Default: 2.

Multiple Documentation Generators​

You can define as many documentation generators as needed. Each top-level key under docs.generate becomes a CLI argument:

atmos.yaml

docs:
  generate:
    # Generate project README
    readme:
      input:
        - "./README.yaml"
      template: "./templates/README.md.gotmpl"
      output: "./README.md"

    # Generate release notes
    release-notes:
      input:
        - "./CHANGELOG.yaml"
      template: "./templates/release-notes.gotmpl"
      output: "./RELEASE_NOTES.md"

    # Generate component documentation
    component-docs:
      input:
        - "./docs/components.yaml"
      template: "./templates/components.md.gotmpl"
      output: "./docs/COMPONENTS.md"

Then invoke each generator by name:

atmos docs generate readme
atmos docs generate release-notes
atmos docs generate component-docs

Template Example​

Templates use Go templating with Gomplate functions:

templates/README.md.gotmpl

{{- $data := (ds "config") -}}

# {{ $data.name | default "Project Title" }}

{{ $data.description | default "No description provided." }}

{{ if has $data "extra_info" }}
## Additional Information

{{ $data.extra_info }}
{{ end }}

{{ if has $data "terraform_docs" }}
## Terraform Documentation

{{ $data.terraform_docs }}
{{ end }}

Input File Sources​

Local Sources​

Supports absolute paths, relative paths, and paths relative to base-dir:

docs:
  generate:
    readme:
      input:
        # Absolute path
        - "/Users/me/Documents/README.yaml"
        # Relative to current directory
        - "./README.yaml"
        # Relative to base-dir
        - "terraform/README.yaml"

Remote Sources​

Atmos uses go-getter for downloading remote files:

docs:
  generate:
    readme:
      input:
        - "https://raw.githubusercontent.com/org/repo/main/README.yaml"
      template: "https://raw.githubusercontent.com/org/repo/main/README.md.gotmpl"