Skip to content

Commit 63f6395

Browse files
cytopiacytopia
authored
Merge pull request #2 from cytopia/release-0.2
Allow for infile replacements
2 parents 6ccc51f + f7e4fd7 commit 63f6395

File tree

3 files changed

+281
-21
lines changed

3 files changed

+281
-21
lines changed

‎Dockerfile‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ RUN set -x \
4040
# Use a clean tiny image to store artifacts in
4141
FROM alpine:latest
4242
COPY --from=builder /go/src/github.com/segmentio/terraform-docs/bin/linux-amd64/terraform-docs /usr/local/bin/terraform-docs
43+
COPY ./data/docker-entrypoint.sh /docker-entrypoint.sh
44+
45+
ENV WORKDIR /docs
4346
WORKDIR /docs
44-
ENTRYPOINT ["/usr/local/bin/terraform-docs"]
45-
CMD ["--version"]
47+
48+
CMD ["terraform-docs", "--version"]
49+
ENTRYPOINT ["/docker-entrypoint.sh"]

‎README.md‎

Lines changed: 147 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,18 @@
44
[![Tag](https://img.shields.io/github/tag/cytopia/docker-terraform-docs.svg)](https://github.com/cytopia/docker-terraform-docs/releases)
55
[![](https://images.microbadger.com/badges/version/cytopia/terraform-docs:latest.svg)](https://microbadger.com/images/cytopia/terraform-docs:latest "terraform-docs")
66
[![](https://images.microbadger.com/badges/image/cytopia/terraform-docs:latest.svg)](https://microbadger.com/images/cytopia/terraform-docs:latest "terraform-docs")
7+
[![](https://img.shields.io/badge/github-cytopia%2Fdocker--terraform--docs-red.svg)](https://github.com/cytopia/docker-terraform-docs "github.com/cytopia/docker-terraform-docs")
78
[![License](https://img.shields.io/badge/license-MIT-%233DA639.svg)](https://opensource.org/licenses/MIT)
89

910

1011
[![Docker hub](http://dockeri.co/image/cytopia/terraform-docs)](https://hub.docker.com/r/cytopia/terraform-docs)
1112

1213

13-
## Official project
14+
Dockerized version of [terraform-docs](https://github.com/segmentio/terraform-docs)<sup>[1]</sup>,
15+
which additionally implements `terraform-docs-replace` allowing you to automatically and safely
16+
replace the `terraform-docs` generated output infile.
1417

15-
https://github.com/segmentio/terraform-docs
18+
<sub>[1] Official project: https://github.com/segmentio/terraform-docs</sub>
1619

1720

1821
## Available Docker image versions
@@ -30,6 +33,17 @@ https://github.com/segmentio/terraform-docs
3033
| `0.1.0` | [Tag: v0.1.0](https://github.com/segmentio/terraform-docs/tree/v0.1.0) |
3134

3235

36+
## Environment variables
37+
38+
The following Docker environment variables are available. These will only need to be used when
39+
using `terraform-docs-replace`.
40+
41+
| Variable | Default | Required | Comment |
42+
|----------|---------|----------|---------|
43+
| DELIM_START | `<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->` | No | The starting delimiter in the file in where you want to replace the `terraform-docs` output. |
44+
| DELIM_CLOSE | `<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->` | No | The ending delimiter in the file in where you want to replace the `terraform-docs` output. |
45+
46+
3347
## Docker mounts
3448

3549
The working directory inside the Docker container is `/docs/` and should be mounted locally to
@@ -43,21 +57,25 @@ Create markdown output and sent to stdout:
4357
```bash
4458
docker run --rm \
4559
-v $(pwd):/docs \
46-
--sort-inputs-by-required --with-aggregate-type-defaults md .
60+
cytopia/terraform-docs \
61+
--sort-inputs-by-required terraform-docs --with-aggregate-type-defaults md .
4762
```
4863

4964
#### Store in file
5065
Create README.md with `terraform-docs` output:
5166
```bash
5267
docker run --rm \
5368
-v $(pwd):/docs \
54-
--sort-inputs-by-required --with-aggregate-type-defaults md . > README.md
69+
cytopia/terraform-docs \
70+
terraform-docs --sort-inputs-by-required --with-aggregate-type-defaults md . > README.md
5571
```
5672

5773
#### Replace in README.md
5874
Replace current `terraform-docs` blocks in README.md with current one in order to automatically
5975
keep it up to date. For this to work, the `terraform-docs` information must be wrapped with the
60-
following delimiter:
76+
following delimiter by default:
77+
78+
`README.md:`
6179
```markdown
6280
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
6381
## Inputs
@@ -66,20 +84,130 @@ following delimiter:
6684
```
6785

6886
```bash
69-
# Save output in variable
70-
DOCS="$(
71-
docker run --rm \
72-
-v $(pwd):/docs \
73-
--sort-inputs-by-required --with-aggregate-type-defaults md .
74-
)"
75-
76-
# Create new README
77-
grep -B 100000000 -F '<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->' README.md > README.md.tmp
78-
printf "${DOCS}\n\n" >> README.md.tmp
79-
grep -A 100000000 -F '<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->' README.md >> README.md.tmp
80-
81-
# Overwrite old README
82-
mv -f README.md.tmp README.md
87+
# Path to README.md must be specified as last command.
88+
# Note that the command changes from terraform-docs to terraform-docs-replace
89+
docker run --rm \
90+
-v $(pwd):/docs \
91+
cytopia/terraform-docs \
92+
terraform-docs-replace --sort-inputs-by-required --with-aggregate-type-defaults md README.md
93+
```
94+
95+
#### Replace in INFO.md with different delimiter
96+
You are able to use different delimiter. Let's imagine the following delimiter:
97+
98+
`INFO.md:`
99+
```markdown
100+
<!-- TFDOC_START -->
101+
## Inputs
102+
...
103+
<!-- TFDOC_END -->
104+
```
105+
106+
```bash
107+
# Path to INFO.md must be specified as last command.
108+
# Note that the command changes from terraform-docs to terraform-docs-replace
109+
docker run --rm \
110+
-v $(pwd):/docs \
111+
-e DELIM_START='TFDOC_START' \
112+
-e DELIM_CLOSE='TFDOC_END' \
113+
cytopia/terraform-docs \
114+
terraform-docs-replace --sort-inputs-by-required --with-aggregate-type-defaults md INFO.md
115+
```
116+
117+
#### Example Makefile
118+
You can add the following Makefile to your project for easy generation of terraform-docs output in
119+
a Terraform module. It takes into consideration the Main module, sub-modules and examples.
120+
121+
```make
122+
.PHONY: gen _gen-main _gen-examples _gen-modules
123+
124+
CURRENT_DIR = $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
125+
TF_EXAMPLES = $(sort $(dir $(wildcard $(CURRENT_DIR)examples/*/)))
126+
TF_MODULES = $(sort $(dir $(wildcard $(CURRENT_DIR)modules/*/)))
127+
TF_DOCS_VERSION = 0.6.0
128+
129+
# Adjust your delimiter here or overwrite via make arguments
130+
DELIM_START = <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
131+
DELIM_CLOSE = <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
132+
133+
gen:
134+
@echo "################################################################################"
135+
@echo "# Terraform-docs generate"
136+
@echo "################################################################################"
137+
@$(MAKE) _gen-main
138+
@$(MAKE) _gen-examples
139+
@$(MAKE) _gen-modules
140+
141+
_gen-main:
142+
@echo "------------------------------------------------------------"
143+
@echo "# Main module"
144+
@echo "------------------------------------------------------------"
145+
@if docker run --rm \
146+
-v $(CURRENT_DIR):/docs \
147+
-e DELIM_START='$(DELIM_START)' \
148+
-e DELIM_CLOSE='$(DELIM_CLOSE)' \
149+
cytopia/terraform-docs:${TF_DOCS_VERSION} \
150+
terraform-docs-replace --sort-inputs-by-required --with-aggregate-type-defaults md README.md; then \
151+
echo "OK"; \
152+
else \
153+
echo "Failed"; \
154+
exit 1; \
155+
fi
156+
157+
_gen-examples:
158+
@$(foreach example,\
159+
$(TF_EXAMPLES),\
160+
DOCKER_PATH="examples/$(notdir $(patsubst %/,%,$(example)))"; \
161+
echo "------------------------------------------------------------"; \
162+
echo "# $${DOCKER_PATH}"; \
163+
echo "------------------------------------------------------------"; \
164+
if docker run --rm \
165+
-v $(CURRENT_DIR):/docs \
166+
-e DELIM_START='$(DELIM_START)' \
167+
-e DELIM_CLOSE='$(DELIM_CLOSE)' \
168+
cytopia/terraform-docs:${TF_DOCS_VERSION} \
169+
terraform-docs-replace --sort-inputs-by-required --with-aggregate-type-defaults md $${DOCKER_PATH}/README.md; then \
170+
echo "OK"; \
171+
else \
172+
echo "Failed"; \
173+
exit 1; \
174+
fi; \
175+
)
176+
177+
_gen-modules:
178+
@$(foreach module,\
179+
$(TF_MODULES),\
180+
DOCKER_PATH="modules/$(notdir $(patsubst %/,%,$(module)))"; \
181+
echo "------------------------------------------------------------"; \
182+
echo "# $${DOCKER_PATH}"; \
183+
echo "------------------------------------------------------------"; \
184+
if docker run --rm \
185+
-v $(CURRENT_DIR):/docs \
186+
-e DELIM_START='$(DELIM_START)' \
187+
-e DELIM_CLOSE='$(DELIM_CLOSE)' \
188+
cytopia/terraform-docs:${TF_DOCS_VERSION} \
189+
terraform-docs-replace --sort-inputs-by-required --with-aggregate-type-defaults md $${DOCKER_PATH}/README.md; then \
190+
echo "OK"; \
191+
else \
192+
echo "Failed"; \
193+
exit 1; \
194+
fi; \
195+
)
196+
```
197+
198+
#### Travis CI integration
199+
With the above Makefile in place, you can easily add a Travis CI rule to ensure the terraform-docs
200+
output is always up-to-date and will fail otherwise (due to git changes):
201+
```yml
202+
---
203+
sudo: required
204+
services:
205+
- docker
206+
before_install: true
207+
install: true
208+
script:
209+
- make gen
210+
- git diff --quiet || { echo "Build Changes"; git diff; git status; false; }
83211
```
84212

85213

‎data/docker-entrypoint.sh‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
#!/bin/sh
2+
3+
set -e
4+
set -u
5+
6+
###
7+
### Default variables
8+
###
9+
DEF_DELIM_START='<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->'
10+
DEF_DELIM_CLOSE='<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->'
11+
12+
13+
###
14+
### Environment variables
15+
###
16+
17+
# Set delimiter
18+
if ! env | grep -q '^DELIM_START='; then
19+
DELIM_START="${DEF_DELIM_START}"
20+
fi
21+
if ! env | grep -q '^DELIM_CLOSE='; then
22+
DELIM_CLOSE="${DEF_DELIM_CLOSE}"
23+
fi
24+
25+
26+
###
27+
### Helper functions
28+
###
29+
30+
# Returns all but the last argument as an array using a POSIX-compliant method
31+
# for handling arrays.
32+
# Credit: https://gist.github.com/akutz/7a39159bbbe9c299c79f1d2107ef1357
33+
trim_last_arg() {
34+
_l="${#}" _i=0 _j="$((_l-1))" && while [ "${_i}" -lt "${_l}" ]; do
35+
if [ "${_i}" -lt "${_j}" ]; then
36+
printf '%s\n' "${1}" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/"
37+
fi
38+
shift; _i="$((_i+1))"
39+
done
40+
echo " "
41+
}
42+
43+
44+
###
45+
### Arguments appended?
46+
###
47+
if [ "${#}" -ge "1" ]; then
48+
49+
###
50+
### Custom replace operation
51+
###
52+
if [ "${1}" = "terraform-docs-replace" ]; then
53+
54+
# Remove first argument "replace"
55+
shift;
56+
57+
# Store and Remove last argument (filename)
58+
eval MY_FILE="\${$#}" # store last argument
59+
args="$(trim_last_arg "${@}")" # get all the args except the last arg
60+
eval "set -- ${args}" # update the shell's arguments with the new value
61+
62+
63+
# Check if file exists
64+
if [ ! -f "${WORKDIR}/${MY_FILE}" ]; then
65+
>&2 echo "Error, ${MY_FILE} not found in: ${WORKDIR}/${MY_FILE}"
66+
exit 1
67+
fi
68+
# Check if starting delimiter exists in file
69+
if ! grep -Fq "${DELIM_START}" "${WORKDIR}/${MY_FILE}"; then
70+
>&2 echo "Error, Starting delimiter not found ${MY_FILE}: '${DELIM_START}'"
71+
exit 1
72+
fi
73+
# Check if closint delimiter exists in file
74+
if ! grep -Fq "${DELIM_CLOSE}" "${WORKDIR}/${MY_FILE}"; then
75+
>&2 echo "Error, Closing delimiter not found ${MY_FILE}: '${DELIM_CLOSE}'"
76+
exit 1
77+
fi
78+
79+
# Get owner and permissions of current file
80+
UID="$(stat -c %u "${WORKDIR}/${MY_FILE}")"
81+
GID="$(stat -c %g "${WORKDIR}/${MY_FILE}")"
82+
PERM="$(stat -c %a "${WORKDIR}/${MY_FILE}")"
83+
84+
# Get terraform-docs output
85+
>&2 echo "terraform-docs ${*} ${WORKDIR}/$(dirname ${MY_FILE})"
86+
DOCS="$(terraform-docs "${@}" "${WORKDIR}/$(dirname ${MY_FILE})")"
87+
88+
# Create temporary README.md
89+
mkdir -p /tmp
90+
grep -B 100000000 -F "${DELIM_START}" "${WORKDIR}/${MY_FILE}" > /tmp/README.md
91+
printf "${DOCS}\n\n" >> /tmp/README.md
92+
grep -A 100000000 -F "${DELIM_CLOSE}" "${WORKDIR}/${MY_FILE}" >> /tmp/README.md
93+
94+
# Adjust permissions of temporary file
95+
chown ${UID}:${GID} /tmp/README.md
96+
chmod ${PERM} /tmp/README.md
97+
98+
# Overwrite existing file
99+
mv -f /tmp/README.md "${WORKDIR}/${MY_FILE}"
100+
exit 0
101+
102+
###
103+
### terraform-docs command
104+
###
105+
elif [ "${1}" = "terraform-docs" ]; then
106+
exec "${@}"
107+
108+
###
109+
### Unsupported command
110+
###
111+
else
112+
>&2 echo "Error, Unsupported command."
113+
>&2 echo "Usage: cytopia/terraform-docs terraform-docs <ARGS> ."
114+
>&2 echo " cytopia/terraform-docs terraform-docs-replace <ARGS>"
115+
>&2 echo
116+
>&2 echo "terraform-docs Output as expected from terraform-docs"
117+
>&2 echo "terraform-docs-replace Same as above, but replaces directly inside README.md"
118+
>&2 echo " if DELIM_START and DELIM_CLOSE are found."
119+
exit 1
120+
121+
fi
122+
123+
###
124+
### No arguments appended
125+
###
126+
else
127+
exec terraform-docs --version
128+
fi

0 commit comments

Comments
 (0)