# 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:

```yaml
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.

```yaml
{{- $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:

```yaml
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`:

```gotemplate
{{- $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](https://github.com/cloudposse/atmos/tree/main/tests/fixtures/scenarios/docs-generate/native-terraform),
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:

```shell
atmos docs generate readme2
atmos docs generate release-notes
```

## Usage

```shell
atmos docs generate readme
```

## Supported Sources for README.yaml and template

### Local Sources

It supports the following local file sources:

- Absolute paths

  ```yaml
  docs:
    generate:
      readme:
        input:
          - "/Users/me/Documents/README.yaml"
        template: "/Users/me/Documents/README.md.gotmpl"
  ```

- Paths relative to the current working directory

  ```yaml
  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)

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

### Remote Sources

To download remote files, Atmos uses [`go-getter`](https://github.com/hashicorp/go-getter)
(used by [Terraform](https://www.terraform.io/) for downloading modules)