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>
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>
terraform-docs version constraints is almost identical to the syntax
used by Terraform. A version constraint is a string literal containing
one or more condition, which are separated by commas.
```yaml
version: ">= 0.13.0, < 1.0.0"
```
Each condition consists of an operator and a version number. A version
number is a series of numbers separated by dots (e.g. `0.13.0`). Note
that version number should not have leading `v` in it.
Valid operators are as follow:
- `=` (or no operator): allows for exact version number.
- `!=`: exclude an exact version number.
- `>`, `>=`, `<`, and `<=`: comparisons against a specific version.
- `~>`: only the rightmost version component to increment.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
As of `v0.13.0` flags `--show-all` and `--hide-all` are deprecated in
favor of explicit use of `--show` and `--hide`. In other words when
`--show <section>` is used, only `<section>` will be shown. If you want
to show multiple sections and hide the rest you can specify multiple
`--show` flags. The same logic is also applied to `--hide`.
# show 'inputs' and hide everything else
$ terraform-docs --show inputs <formatter>
# show 'inputs' and show 'outputs' and hide everything else
$ terraform-docs --show inputs --show outputs <formatter>
# hide 'header' and show everything else
$ terraform-docs --hide header <formatter>
# hide 'header' and hide 'providers' and show everything else
$ terraform-docs --hide header --hide providers <formatter>
Note: Using `--show` or `--hide` CLI flag will completely override the
values from `.terraform-docs.yml`. Example:
$ cat .terraform-docs.yml
sections:
show:
- inputs
- outputs
# example 1: this will only show 'providers'
$ terraform-docs --show providers .
# example 2: this will hide 'inputs' and hide 'providers' and show everything else
$ terraform-docs --hide inputs --hide providers .
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This deprecates sort by flags in favor of their corresponding dynamic
valued ones. Affected flags are:
- `--sort-by-required`
- `--sort-by-type`
In return new `--sort-by string` is added with following values:
- `name` (default)
- `required`
- `type`
Note that the behavior of `--sort bool` was not changed and to disable
sorting altogether you can run `--sort false`.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Enables a footer to be appended to the end of a generated document
sourced from tf files or documents in the same way as the header
Adds the `footer-from` field to the config yml
Adds the `--footer-from` flag to the cli
Signed-off-by: Simon Clifford <siclifford@gmail.com>
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This is going to preserve line-ending of extracted header text as they
are provided by users. In other words we are going to always assume the
header text is formatted in the "intended" way by users. So we're never
going to modify line-endings and won't append `<SPACE><SPACE>` at the
end of paragraph lines.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
There are two modes for saving into file:
- inject: partially replace the target file with generated output
- replace: completely replace the target file with generated output
The output generated by formatters (markdown, asciidoc, etc) will be
inserted into a template before getting saved into the file. This
template can be customized with '--output-template' CLI flag or
corresponding item in '.terraform-docs.yml' config file. Its default
value is:
```
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
```
This consists of three items, all of them are mandatory:
- begin comment
- content variable
- end comment
You may change the wording of comment as you wish, but the comment must
be present in the template.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
Two new flags are added: '--default bool' and '--type bool' to
control the visibility of Default and Type columns and section
respectively in Markdown and AsciiDoc.
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
* Allow reading header from a markdown file
* wording
* add supports for .adoc and .txt as well
* wording
* revert docs
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
* Mark variables not required if default set to null
* Move github.com/hashicorp/terraform-config-inspect to internal/tfconfig
Internally we depend on terraform-config-inspect, but at the moment
they state that they consider the project is feature-complete and
they do not accept any enhancement pull requests, as such we've
decided to bring over the project as internal package here rather than
being a vendor dependency and apply the fix from @jstewmon from
https://github.com/hashicorp/terraform-config-inspect/pull/24 directly
here.
Since the terraform-config-inspect is considered to be feature-complete
we don't expect to have any more changes on the package, and if there
was a change on upstream we're going to bring it down in the
corresponding package.
* Add notice to the new package
* add license of terraform-config-inspect code
* fix tests after merging master
* fix test after merge master
* show 'required' attribute in JSON, XML, YAML
* update docs
* Allow users to pass '--output-values'
Pass empty string to CreateModule.outputValuePath
* Fix bug causing 'pretty' tests to fail
* Link formats documentation in README (#181)
Co-authored-by: Khosrow Moossavi <khos2ow@gmail.com>
* docs: Auto generate formats document from examples (#192)
* Auto generate formats document from examples
* fix lint issues
* refactor: Add tfconf.Options to load Module with (#193)
* Update Changelog
* Allow users to pass '--output-values'
Read the outputValuesPath from an env variable
Use an env var with a path for '--output-values'
Update Changelog
Use an env var with a path for '--output-values'
Update Changelog
properly write output values for evrythng but yaml
* Fix failing json+yaml tests
* Remove unneeded code block from output.go
* Remove unused import statement from output.go
* Fix some noob mistakes
* Create two flags to use for output value injection
* Fix bug vanilla commands+build test to fail
* Modify all tests and add new for outputvalues
* Modify to include many output types
* Optimize imports to appease checkfmt
* Create loadOutputValues function
* Fix linter issue
* Code review fixes. Hopefully the final commit!
* appease linter
* Not allow sensitive output values to be injected
* Remove trailing slash from tests
* Remove default values from `--output-values-from`
Co-authored-by: Martyn Ranyard <iMartyn@users.noreply.github.com>
Co-authored-by: Khosrow Moossavi <khos2ow@gmail.com>
Supported comment formats is:
- jsdoc, c or java-like multi-line comment `/** **/`
BREAKING CHANGE: - In the JSON format respone, module "Comment" has been renamed to module `header`.
Supported comment formats are:
- multi-lines start with `#` comment format
- multi-lines start with `//` comment format
Unsupported comments formats is:
- jsdoc, c or java-like multi-line comment `/** **/`
* Show 'providers' information
* Fix for unsorted providers list
BREAKING CHANGE: - With Terraform 0.12 the information about `providers` being used in the module will be generated by default. This will cause the first generation of documents with the latest release of `terraform-docs` binary be slightly different than before, now there will be `Providers` section in Markdown and `providers` block in JSON. You can ignore this by using new `--no-providers` flag if you choose to.
Originally-Authored-By: Thomas Alton <thomas.alton@gmail.com>
Original-Pull-Request: #113
* Support 0.12 configuration
* Move code out of GOPATH for CircleCI
* cleanup
* Rename 'variables' back to 'input' just for now
* Normalizing 'print.s.Settings' usage
* Normalize settings continued
* Remove '--providers' functionality for now
* Adjust 'commands' based on moarta's changes
* Adjust 'pkg/doc' based on moarta's changes
* Adjust 'pkg/print/json' based on moarta's changes
* Fix json tests
* don't trim whitespaces from .tf files
* Adjust 'pkg/print/pretty' based on moarta's changes
* Fix pretty tests
* don't trim whitespaces from .golden files
* Show 'n/a' for empty description for 'pretty'
* Show 'any' if type of input variable is missing
* Adjust 'pkg/print/markdown/document' based on moarta's changes
* Fix document tests
* move back vendor files
* Adjust 'pkg/print/markdown/table' based on moarta's changes
* fix lint issue
* Fix table tests
* figure out input type based on default value if tpye not explicitly defined
* don't escape ( ) [ ] { }, as they don't cause any issue
Authored-by: Thomas Alton <thomas.alton@gmail.com>
Co-authored-by: Khosrow Moossavi <khos2ow@gmail.com>
* HTML-ize code blocks inside a markdown table. Single line break.
Add support for embedding markdown code blocks inside markdown tables
Add support for single-line breaks: when the line ends with 2 spaces, place
a single <br>.
* Fix the testsuite, todo improve the escape code for document
* Add the WithIndent testdata
