<br /> provides additional support for XHTML without breaking
compatibility with HTML. This can be useful when trying to publish
documentation generated by terraform-docs to XHTML based solutions
Signed-off-by: christophe.vandekerchove <christophe.vandekerchove@scalepad.com>
Prepend any type of resource, including `resource`, `data`, `module`,
`variable`, and `output` with a comment including "terraform-docs-ignore"
to exclude it from the generated output.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Moving terraform-docs/plugin-sdk standalone module to in-tree, because
maintaining both of them, specifically if anything needs to be added to
Config, or terraform will required dual effort on both repository. As
such now everything is consolidated under one repository. Example usage
for plugin developer after this move is as follow:
```go
package main
import (
_ "embed" //nolint
"github.com/terraform-docs/terraform-docs/plugin"
"github.com/terraform-docs/terraform-docs/print"
"github.com/terraform-docs/terraform-docs/template"
"github.com/terraform-docs/terraform-docs/terraform"
)
func main() {
plugin.Serve(&plugin.ServeOpts{
Name: "template",
Version: "0.1.0",
Printer: printer,
})
}
//go:embed sections.tmpl
var tplCustom []byte
// Print the custom format template. You have all the flexibility to generate
// the output however you choose to.
func printer(config *print.Config, module *terraform.Module) (string, error) {
tpl := template.New(config,
&template.Item{Name: "custom", Text: string(tplCustom)},
)
rendered, err := tpl.Render("custom", module)
if err != nil {
return "", err
}
return rendered, nil
}
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Add one extra special variable the `content`:
- `{{ .Module }}`
As opposed to the other variables, which are generated sections based on
a selected formatter, the `{{ .Module }}` variable is just a `struct`
representing a Terraform module.
It can be used to build highly complex and highly customized content:
```yaml
content: |-
## Resources
{{ range .Module.Resources }}
- {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
{{- end }}
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Up to now there was only one way to enable recursive execution and that
was with `--recursive` CLI flag. This enables the same behavior but
within config file (i.e. `.terraform-docs.yml`)
Example:
```yaml
recursive:
enabled: false
path: modules
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Considering the file strucutre below of main module and its submodules,
now it is possible to generate documentation for them main and all its
submodules in one execution, with `--recursive` flag.
Note that generating documentation recursively is allowed only with
`--output-file` set.
Path to find submodules can be configured with `--recursive-path`
(defaults to `modules`).
Each submodule can also have their own `.terraform-docs.yml` confi file,
to override configuration from root module.
```
.
├── README.md
├── main.tf
├── modules
│ └── my-sub-module
│ ├── README.md
│ ├── main.tf
│ ├── variables.tf
│ └── versions.tf
├── outputs.tf
├── variables.tf
└── versions.tf
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
The updated order of trying to look up for .terraform-docs.yml config
file, now, is:
1. root of module directory
2. `.config/` folder at root of module directory
3. current directory
4. `.config/` folder at current directory
5. `$HOME/.tfdocs.d/`
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
New flag, `--lockfile`, is added to control whether ignore reading
.terraform.lock.hcl file in an attempt to extract the exact version of
provider being used or not. Default is true.
If set to true, exact version of provider available in lock file at the
time of execution will be extracted. If set to false, the version in .tf
file will be used (either exact, or a constrained version: >=, ~>, ...)
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
adding option to compare outputted file with generated
terraform-doc and fail if different
Signed-off-by: Ricardo Herrera <rickhl@outlook.com>
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
New psuedo section `all` is added and can be used to show or hide _all_
sections. This can be used as a replacement for, now, deprecated and
removed `--show-all` and `--hide-all` flags.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
In v0.13.0 flags `--show-all` and `--hide-all` have been deprecated. And
they are completely being removed now (two releases after original
announcement)
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This is to control the generated HTML tags inside markdown output. If
set to false no html tags (e.g. `<br>`, `<pre>`) will be generated. And
as a workaround the multi-line codeblock will be converted to single
line with linebreak converted to `<SPACE>`.
For example:
```
{
"bar": {
"bar": "bar",
"foo": "bar"
},
"buzz": [
"fizz",
"buzz"
],
"fizz": []
}
```
will be converted to:
```
{ "bar": { "bar": "bar", "foo": "bar" }, "buzz": [ "fizz", "buzz" ], "fizz": [] }
```
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Local relative files can be included automatically in the generated
content with `{{ include "..." }} function. This can be very useful
for:
- inject arbitrary markdown files in between sections
- automatically include example usage
````yaml
content: |-
include any relative files
{{ include "relative/path/to/file" }}
or examples
```hcl
{{ include "examples/foo/main.tf" }}
```
````
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Generated content can be customized further away with `content` in configuration.
If the `content` is empty the default orders of section is used. `content` is a
Go template with following additional variables:
- `{{ .Header }}`
- `{{ .Footer }}`
- `{{ .Inputs }}`
- `{{ .Modules }}`
- `{{ .Outputs }}`
- `{{ .Providers }}`
- `{{ .Requirements }}`
- `{{ .Resources }}`
```yaml
content: |-
Any arbitrary text can be placed anywhere in the content
{{ .Header }}
and even in between sections
{{ .Providers }}
and they don't even need to be in the default order
{{ .Outputs }}
{{ .Inputs }}
```
These variables are the generated output of individual sections in the selected
formatter. For example `{{ .Inputs }}` is Markdown Table representation of inputs
when formatter is set to `markdown table` and AsciiDoc Document representation
when formatter is set to `asciidoc document` and so on.
Compatible formats for customized content are:
- `asciidoc document`
- `asciidoc table`
- `markdown document`
- `markdown table`
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
