Description
First I'd like to thank you all for such a great tool to help document the nightmare that is a complex multi-module Terraform script.
What problem are you facing?
There is no way to sort a custom content template excerpt (slice, e.g. ModuleCalls) by a key (e.g. Position.Line). Also depends_on is missing, but would not help, because I cannot sort by a property anyway. And the order is alphabetical, not in the order of appearance.
I have this .terraform-docs.yml configuration:
.terraform-docs.yml configuration
formatter: "markdown" # this is required
header-from: assets/header.md
footer-from: ""
recursive:
enabled: true
path: modules
include-main: false
sections:
hide: []
show: []
content: |-
{{ .Header }}
## Contents
<blockquote>
- [Requirements](#requirements)
- [Providers](#providers)
- [Modules](#modules)
{{- range .Module.ModuleCalls }}
- [{{ .Name }}](#{{ .Name }})
{{- end }}
- [Inputs](#inputs)
- [Outputs](#outputs)
- [resource](#resource)
{{- range .Module.Resources }}
{{- if eq .GetMode "resource" }}
{{- $spec := split "." .Spec }}
- {{ $spec._1 }}
{{- end -}}
{{- end }}
- [output](#output)
{{- range .Module.Outputs }}
- {{ .Name }}
{{- end -}}
</blockquote>
{{ .Requirements }}
{{ .Providers }}
## Modules
{{- range .Module.ModuleCalls }}
<blockquote>
### `{{ .Name }}`
{{ .Description.Raw }}
| | |
|:--- |:--- |
| Module location | `{{ .Source }}`
{{- $position := split "/" .Position.Filename }}
| Called in file | `{{ $position._2 }}#{{ .Position.Line }}`
</blockquote>
{{- end }}
## Inputs
{{- range .Module.Inputs }}
<blockquote>
### `{{ .Name }}`
{{- if .Required }}
(**Required**)
{{- else }}
(*Optional*)
{{- end }}
{{ .Description }}
<details style="border-top-color: inherit; border-top-width: 0.1em; border-top-style: solid; padding-top: 0.5em; padding-bottom: 0.5em;">
<summary>Show type structure and defaults</summary>
**Type**:
```hcl
{{ .Type }}
````
{{- if or .HasDefault }}
**Default**:
```json
{{ .GetValue }}
```
{{- end }}
</details>
</blockquote>
{{- end }}
## Outputs
### `resource`
| Type | Name | File | Line |
| :--- | :--- | :--- | ---: |
{{- range .Module.Resources }}
{{- if eq .GetMode "resource" }}
{{- $split_result := split "." .Spec }}
| _{{ $split_result._0 }}_ | **{{ $split_result._1 }}** | `{{ .Position.Filename }}` | #{{ .Position.Line }} |
{{- end -}}
{{- end }}
### `output`
| Name | Description | Sensitive | File | Line |
| :--- | :---------- | --------- | :--- | ---: |
{{- range .Module.Outputs }}
| **{{ .Name }}** | {{ .Description }} | `{{ .Sensitive }}` | `{{ .Position.Filename }}` | #{{ .Position.Line }} |
{{- end -}}
{{ .Footer }}
output:
file: "README.md"
mode: replace
template: |-
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
output-values:
enabled: false
from: ""
sort:
enabled: true
by: required
settings:
anchor: true
color: true
default: true
description: true
escape: true
hide-empty: false
html: false
indent: 2
lockfile: true
read-comments: true
required: true
sensitive: true
type: trueThe relevant part is
- [Modules](#modules)
{{- range .Module.ModuleCalls }}
- [{{ .Name }}](#{{ .Name }})
{{- end }}I cannot use sort or sortBy of any sorts, because it does not seem to be allowed.
If I could use sort, I probably might solve my problem: the modules appear in an alphabetical order rather than by the order of appearance in the main.tf (which would correspond to .Position.Line) or some depends_on order.
How could terraform-docs help solve your problem?
Solution idea 1
Would it perhaps be possible to include sort from Go templates standard library (or at least I think it is)?
I am not too well-versed in Go, but I think something like the following woud then become possible:
{{ $sortedModules := slice }}
{{ range .Module.ModuleCalls }}
{{ $sortedModules = append $sortedModules . }}
{{ end }}
{{ $sortedModules = sort $sortedModules "Position.Line" }}and then
{{- range $sortedModules }}
### {{ .Name }}
{{ end }}Solution idea 2
Have the ModuleCalls map return the list in the order of appearance or in the order of depends_on properties - if that's possible.
Note
If you need any additional information, let me know.