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 field | Available data |
|---|---|
.Inputs, .RequiredInputs, .OptionalInputs | Names, types, descriptions, defaults, required status, and source positions; .GetValue and .HasDefault methods |
.Outputs | Names, descriptions, sensitivity, and source positions; state values are not loaded |
.Providers, .Requirements | Provider and version requirement information |
.ModuleCalls | Module names, sources, versions, descriptions, and source positions |
.Resources | Managed resources and data sources; .GetMode, .Spec, .URL, and source positions |
.Header, .Footer | Header 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 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_dirdefined inatmos.yamlCLI 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.generateinatmos.yaml, such asreadmeorrelease-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 theATMOS_SKIP_HOOKSenvironment variable. Hooks that a governing policy marksrequiredcannot 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
before.docs.generatehooks run first. A failing before-hook aborts the command before any file is written.- The document is generated.
after.docs.generatehooks run with the outcome. By default an after-hook runs only on success; setwhen: failureorwhen: alwaysto run it on failure too. See reacting to success or failure.- If generation succeeded and an after-hook fails, the command fails unless that hook sets
on_failure: warnoron_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.