Skip to content

Commit b261712

Browse files
khos2owkhos2ow
committed
Initial commit of formatter template
Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
1 parent f606143 commit b261712

File tree

8 files changed

+421
-1
lines changed

8 files changed

+421
-1
lines changed

‎.gitignore‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Build binaries
2+
tfdocs-format-template
3+
/bin
4+
5+
# Binaries for programs and plugins
6+
*.exe
7+
*.exe~
8+
*.dll
9+
*.so
10+
*.dylib
11+
12+
# Test binary, built with `go test -c`
13+
*.test
14+
15+
# Output of the go coverage tool, specifically when used with LiteIDE
16+
*.out
17+
18+
# Dependency directories
19+
vendor/
20+
21+
# ignore GoLand files (debug config etc...)
22+
/.idea
23+
24+
# ignore vscode files (debug config etc...)
25+
/.vscode
26+
27+
# ignore asdf local versions
28+
/.tool-versions

‎Makefile‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
BUILD_NAME := tfdocs-format-template
2+
3+
BUILD_DIR := bin
4+
PLUGIN_FOLDER ?= ~/.tfdocs.d/plugins
5+
6+
GOOS ?= $(shell go env GOOS)
7+
GOARCH ?= $(shell go env GOARCH)
8+
9+
all: clean verify build
10+
11+
clean:
12+
rm -rf ./$(BUILD_DIR) ./${BUILD_NAME}
13+
14+
verify:
15+
go mod verify
16+
17+
build: clean
18+
CGO_ENABLED=0 go build -o ./$(BUILD_DIR)/$(GOOS)-$(GOARCH)/$(BUILD_NAME)
19+
20+
install: build
21+
mkdir -p $(PLUGIN_FOLDER)
22+
mv ./$(BUILD_DIR)/$(GOOS)-$(GOARCH)/$(BUILD_NAME) $(PLUGIN_FOLDER)
23+
24+
.PHONY: all clean verify build install help

‎README.md‎

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,60 @@
1-
# tfdocs-formatter-template
1+
# tfdocs-format-template
2+
3+
`tfdocs-format-template` is a minimal [terraform-docs] plugin that is built with
4+
[plugin SDK] and is meant to be used as a template for implementing new plugin.
5+
Most of the time you only need to modify and reorder the go template strings defined
6+
in `engine/sections.go`.
7+
8+
## Requirements
9+
10+
- [Go] 1.15+
11+
- [terraform-docs] v0.11+
12+
13+
Optionally for releasing:
14+
15+
- [gox]
16+
17+
## Installation
18+
19+
In order to install a plugin the following steps are needed:
20+
21+
- download the plugin and place it in `~/.tfdocs.d/plugins` (or `./.tfdocs.d/plugins`)
22+
- make sure the plugin file name is `tfdocs-format-<NAME>` (e.g `<NAME>` should be `template`)
23+
- modify `formatter` of `.terraform-docs.yml` file to be `<NAME>`
24+
25+
**Important notes:**
26+
27+
- if the plugin file name is different than the example above, `terraform-docs` won't
28+
be able to to pick it up nor register it properly.
29+
- you can only use plugin thorough `.terraform-docs.yml` file and it cannot be used
30+
with CLI arguments
31+
32+
## Building
33+
34+
Create a repository from this by clicking `Use this template` and then clone the
35+
newly created repository locally and run the following command:
36+
37+
```bash
38+
make
39+
```
40+
41+
You can then install the plugin to `~/.tfdocs.d/plugins` by running the following:
42+
43+
```bash
44+
make install
45+
```
46+
47+
Additionally you can override the destination of installation:
48+
49+
```bash
50+
PLUGIN_FOLDER=/path/to/plugin/folder make install
51+
```
52+
53+
Note that the plugin has to be built for target OS and archetecture (`make build`
54+
and `make install` do that,) but if you want to redistribute the plugin for other
55+
people to use you have to cross-compile it (for example you can use [gox].)
56+
57+
[terraform-docs]: https://github.com/terraform-docs/terraform-docs
58+
[plugin SDK]: https://github.com/terraform-docs/plugin-sdk
59+
[Go]: https://golang.org/
60+
[gox]: https://github.com/mitchellh/gox

‎engine/engine.go‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/*
2+
Copyright 2021 The terraform-docs Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package engine
18+
19+
import (
20+
"github.com/terraform-docs/plugin-sdk/print"
21+
"github.com/terraform-docs/plugin-sdk/template"
22+
"github.com/terraform-docs/plugin-sdk/terraform"
23+
)
24+
25+
type engine struct{}
26+
27+
// New returns an implementation which satisfies print.Engine interface.
28+
func New() print.Engine {
29+
return &engine{}
30+
}
31+
32+
// Print the custom format template. You have all the flexibility to generate
33+
// the output however you choose to.
34+
func (e *engine) Print(module terraform.Module, settings *print.Settings) (string, error) {
35+
tpl := template.New(settings,
36+
&template.Item{Name: "custom", Text: tplCustom},
37+
&template.Item{Name: "header", Text: tplHeader},
38+
&template.Item{Name: "inputs", Text: tplInputs},
39+
&template.Item{Name: "outputs", Text: tplOutputs},
40+
&template.Item{Name: "requirements", Text: tplRequirements},
41+
&template.Item{Name: "providers", Text: tplProviders},
42+
)
43+
44+
rendered, err := tpl.Render(module)
45+
if err != nil {
46+
return "", err
47+
}
48+
return rendered, nil
49+
}

‎engine/sections.go‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
/*
2+
Copyright 2021 The terraform-docs Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package engine
18+
19+
const (
20+
tplHeader = `
21+
{{- if .Settings.ShowHeader -}}
22+
{{- with .Module.Header -}}
23+
{{ . }}
24+
{{ printf "\n" }}
25+
{{- end -}}
26+
{{ end -}}
27+
`
28+
29+
tplInputs = `
30+
{{- if .Settings.ShowInputs -}}
31+
{{ indent 0 "#" }} Inputs
32+
{{ if not .Module.Inputs }}
33+
No inputs.
34+
{{ else }}
35+
{{- range .Module.Inputs }}
36+
{{ printf "\n" }}
37+
{{ indent 1 "#" }} {{ name .Name }} ` + "`" + `{{ .Type }}` + "`" + `
38+
39+
Description: {{ .Description }}
40+
Default: {{ .Default }}
41+
{{- end }}
42+
{{ end }}
43+
{{ end -}}
44+
`
45+
46+
tplOutputs = `
47+
{{- if .Settings.ShowOutputs -}}
48+
{{ indent 0 "#" }} Outputs
49+
{{ if not .Module.Outputs }}
50+
No outputs.
51+
{{ else }}
52+
| Name | Description | Type | Default |
53+
|------|-------------|------|---------|
54+
{{- range .Module.Outputs }}
55+
- {{ .Name }}
56+
- {{ .Description }}
57+
{{- end }}
58+
{{ end }}
59+
{{ end -}}
60+
`
61+
62+
tplRequirements = `
63+
{{- if .Settings.ShowRequirements -}}
64+
{{ indent 0 "#" }} Requirements
65+
66+
Intentionally don't show requirements to demonstrate the flexibility of the plugin.
67+
{{ end -}}
68+
`
69+
70+
tplResources = `
71+
{{- if .Settings.ShowResources -}}
72+
{{ indent 0 "#" }} Resources
73+
{{ if not .Module.Resources }}
74+
No resources.
75+
{{ else }}
76+
{{- range .Module.Resources }}
77+
- {{ .Name }}
78+
{{- end }}
79+
{{- end }}
80+
{{ end -}}
81+
`
82+
83+
tplProviders = `
84+
{{- if .Settings.ShowProviders -}}
85+
{{ indent 0 "#" }} Providers
86+
{{ if not .Module.Providers }}
87+
No providers.
88+
{{ else }}
89+
{{- range .Module.Providers }}
90+
- {{ .ProviderName }}
91+
{{- end }}
92+
{{- end }}
93+
{{ end -}}
94+
`
95+
96+
tplCustom = `
97+
{{- template "header" . -}}
98+
{{- template "inputs" . -}}
99+
{{- template "outputs" . -}}
100+
{{- template "requirements" . -}}
101+
{{- template "providers" . -}}
102+
{{- template "resources" . -}}
103+
`
104+
)

‎go.mod‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
module github.com/terraform-docs/tfdocs-format-template
2+
3+
go 1.15
4+
5+
require (
6+
github.com/google/go-cmp v0.3.0 // indirect
7+
github.com/hashicorp/go-hclog v0.15.0 // indirect
8+
github.com/hashicorp/go-plugin v1.4.0 // indirect
9+
github.com/kr/pretty v0.1.0 // indirect
10+
github.com/mitchellh/go-testing-interface v1.0.0 // indirect
11+
github.com/stretchr/testify v1.6.1 // indirect
12+
github.com/terraform-docs/plugin-sdk v0.0.0-20210202170709-80cd47c11513
13+
golang.org/x/net v0.0.0-20190620200207-3b0461eec859 // indirect
14+
golang.org/x/text v0.3.2 // indirect
15+
google.golang.org/genproto v0.0.0-20191108220845-16a3f7862a1a // indirect
16+
gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 // indirect
17+
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776 // indirect
18+
)

0 commit comments

Comments
 (0)