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

**File:** `atmos.yaml`

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

**File:** `atmos.yaml`

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

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

## Template Example

Templates use Go templating with Gomplate functions:

**File:** `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`:

```yaml
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](https://github.com/hashicorp/go-getter) for downloading remote files:

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

## Related Commands

- [`atmos docs generate`](/cli/commands/docs/generate) — Generate documentation artifacts
- [`atmos docs`](/cli/commands/docs/usage) — Open Atmos documentation