Skip to main content

atmos docs generate

Use this command to generate one of your documentation artifacts (e.g. a README) as defined by the named section under docs.generate.<KEY> in atmos.yaml.

Replace <KEY> with the name of the section you want to run (for example, readme, release-notes, etc.).

In atmos.yaml, you can define one or more documentation‐generation blocks under docs.generate. Each top‐level key becomes a CLI argument:

docs:
generate:
readme:
base-dir: .
input:
- "./README.yaml"
template: "https://.../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"

For each CLI argument the command combines all local or remote YAML files specified at input and template file then generates the documentation artifact at the respective output folder. In case the template contains terraform_docs key, e.g.

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

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

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

{{ if has $data "extra_info" }}
Extra info: {{ $data.extra_info }}
{{ end }}

{{ if has $data "terraform_docs" }}
## Terraform Docs
{{ $data.terraform_docs }}
{{ end }}

the resultant file will also have a corresponding section rendered. By default terraform.format is set to markdown table, and can also be markdown, tfvars hcl, and tfvars json.

Custom Terraform formatting​

Use the terraform template function to format Terraform documentation yourself. It returns the native parsed terraform-docs module, preserving fields and methods such as .Type.Raw, .Description.Raw, .GetValue, and .Position.Filename. The module is loaded once per document and is also used to generate the existing terraform_docs string.

The terraform function requires a version of Atmos containing this feature. Atmos 1.232.0 and earlier cannot parse templates that call it, even inside {{ with terraform }} or with Terraform generation disabled. Upgrade the Atmos version pinned by your repository before adopting a native template. The guard handles a missing module in a supported version; it does not provide backward compatibility with an undefined function. Older pins can continue using {{ (ds "config").terraform_docs }}.

Configure your template and enable Terraform documentation:

docs:
generate:
readme:
base-dir: .
input:
- "./README.yaml"
template: "./README.md.gomplate"
output: "./README.md"
terraform:
enabled: true
source: .
sort_by: name

In README.md.gomplate:

{{- $data := ds "config" -}}
# {{ $data.name }}

{{ $data.description }}

{{ with terraform }}
## Required Variables
{{ range .RequiredInputs }}
### `{{ .Name }}`

{{ .Description.Raw }}

Type: `{{ .Type.Raw }}`
{{ end }}

## Optional Variables
{{ range .OptionalInputs }}
### `{{ .Name }}`

{{ .Description.Raw }}

Type: `{{ .Type.Raw }}`

Default: `{{ .GetValue }}`
{{ end }}
{{ end }}

You can also iterate directly with {{ range (terraform).Inputs }} when a module is available. Use {{ with terraform }} to handle disabled Terraform generation or a missing configured source directory: the function returns nil in those cases. An empty module returns an object with empty collections. Invalid Terraform or template errors fail generation.

Module fieldAvailable data
.Inputs, .RequiredInputs, .OptionalInputsNames, types, descriptions, defaults, required status, and source positions; .GetValue and .HasDefault methods
.OutputsNames, descriptions, sensitivity, and source positions; state values are not loaded
.Providers, .RequirementsProvider and version requirement information
.ModuleCallsModule names, sources, versions, descriptions, and source positions
.ResourcesManaged resources and data sources; .GetMode, .Spec, .URL, and source positions
.Header, .FooterHeader and footer text loaded by terraform-docs

For terraform_docs, explicit show_providers, show_inputs, and show_outputs settings control visibility, hide_empty omits empty sections, and indent_level sets the Markdown heading level (default 2). Omitted display settings retain the formatter defaults. The built-in readme configuration defaults to hiding providers and showing inputs and outputs; other generator names inherit the formatter's visible sections unless configured otherwise.

Projects with an edition pin before 2026-10-17 retain the previous behavior, which ignored visibility, empty-section, and heading-level settings. Unpinned projects and pins on or after that date honor them. Sorting works in both paths.

The native module retains all parsed sections regardless of the formatter's section-display settings. Your template controls grouping, visibility, escaping, and layout. The sort_by setting determines the module's input ordering.

The terraform function is available only during atmos docs generate rendering. Its native objects are separate from ds "config", which continues to provide merged YAML metadata and the formatted terraform_docs string. Existing templates can keep using {{ (ds "config").terraform_docs }} unchanged. Both .gomplate and .gotmpl filenames work; the configured filename has no required extension.

For a complete example with required, optional, and context-variable sections, definition lists, badges, and collapsible details, see the README template fixture, adapted from the original Cloud Posse component README design.

Dynamic Keys​

If you add a new key under docs.generate—say readme2 or release-notes —you simply pass that key to the CLI:

atmos docs generate readme2
atmos docs generate release-notes

Usage​

atmos docs generate --help
 
atmos docs generate readme

Supported Sources for README.yaml and template​

Local Sources​

It supports the following local file sources:

  • Absolute paths

    docs:
    generate:
    readme:
    input:
    - "/Users/me/Documents/README.yaml"
    template: "/Users/me/Documents/README.md.gotmpl"
  • Paths relative to the current working directory

    docs:
    generate:
    readme:
    input:
    - "./README.yaml"
    template: "./README.md.gotmpl"
  • Paths relative to the base_dir defined in atmos.yaml CLI config file (then resolved as relative to cwd)

    docs:
    generate:
    readme:
    input:
    - "terraform/README.yaml"
    template: "terraform/README.md.gotmpl"

Remote Sources​

To download remote files, Atmos uses go-getter (used by Terraform for downloading modules)

Examples​

# Generate the README
atmos docs generate readme

# Generate it without running any hooks
atmos docs generate readme --skip-hooks

# Skip one hook by name
atmos docs generate readme --skip-hooks=publish-wiki

Arguments​

<KEY>
The name of a section under docs.generate in atmos.yaml, such as readme or release-notes.

Flags​

--skip-hooks
Skip all lifecycle hooks for this run, or pass --skip-hooks=<name>[,<name>] to skip specific hooks by name. Also available as the ATMOS_SKIP_HOOKS environment variable. Hooks that a governing policy marks required cannot be skipped.

Hooks​

Generated documentation often needs to go somewhere else: a wiki, a documentation portal, a bucket, a chat channel. Declare hooks under the generator that produces the document and Atmos runs them around generation, using the same hook kinds and fields as component hooks. The events are before.docs.generate and after.docs.generate.

docs:
generate:
readme:
input:
- "./README.yaml"
template: "./README.md.gotmpl"
output: "./README.md"
hooks:
publish-wiki:
kind: step
type: http
events: [after.docs.generate]
when: success
on_failure: fail
with:
url: "https://example.atlassian.net/wiki/rest/api/content/123456"
method: PUT
headers:
Authorization: "Bearer {{ .env.WIKI_TOKEN }}"
Content-Type: application/json
body: '{"id": "123456", "type": "page", "title": "README", "version": {"number": 2}, "body": {"storage": {"value": "<p>Generated by Atmos</p>", "representation": "storage"}}}'
expect:
status: [200]

The example uses the generic http step against a wiki's REST API. Atmos has no wiki-specific feature; any service that accepts an HTTP request works the same way. To send the generated file's contents instead of fixed text, use a kind: command hook or a script step that reads ATMOS_DOCS_OUTPUT_PATH.

Ordering and failure​

  1. before.docs.generate hooks run first. A failing before-hook aborts the command before any file is written.
  2. The document is generated.
  3. after.docs.generate hooks run with the outcome. By default an after-hook runs only on success; set when: failure or when: always to run it on failure too. See reacting to success or failure.
  4. If generation succeeded and an after-hook fails, the command fails unless that hook sets on_failure: warn or on_failure: ignore.

A hook with no events list runs on both events. Hooks belong to one generator: hooks under readme do not run for release-notes.

Within one event, hooks run in order of hook name. Hooks run with the project root (the directory Atmos was started from, where atmos.yaml is found) as the working directory, not base-dir. Use ATMOS_DOCS_BASE_DIR or ATMOS_DOCS_OUTPUT_PATH to reach the generator's files.

Hook context​

ATMOS_DOCS_TYPE
The generator name, such as readme.
ATMOS_DOCS_OUTPUT_PATH
The resolved path of the generated file.
ATMOS_DOCS_BASE_DIR
The resolved base directory of the generator.

Step templates can use the same values as {{ .docs.type }}, {{ .docs.output_path }}, and {{ .docs.base_dir }}. Documentation hooks have no component or stack, so those values are empty.

Policy​

A governing policy with on: operation and action: hooks applies to documentation generation too. The operation input has component_type: docs, command: generate, the generator name as component, and no stack. See Policy-Driven Hooks and operation input.