Skip to content

Commit d1fba18

Browse files
andreaangiolilloandreaangiolillo
authored
chore: Define a new makefile command for running tfplugindocs (#1829)
1 parent 9cf3f9f commit d1fba18

File tree

4 files changed

+115
-3
lines changed

4 files changed

+115
-3
lines changed

‎GNUmakefile

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ fmt:
5353
gofmt -s -w .
5454

5555
.PHONY: fmtcheck
56-
fmtcheck: # Currently required by tf-deploy compile
56+
fmtcheck: ## Currently required by tf-deploy compile
5757
@sh -c "'$(CURDIR)/scripts/gofmtcheck.sh'"
5858

5959
.PHONY: lint-fix
@@ -121,3 +121,8 @@ scaffold:
121121
@go run ./tools/scaffold/*.go $(name) $(type)
122122
@echo "Reminder: configure the new $(type) in provider.go"
123123

124+
125+
.PHONY: generate-doc
126+
generate-doc: ## Generate the resource documentation via tfplugindocs
127+
./scripts/generate-doc.sh ${resource_name}
128+

‎scripts/generate-doc.sh

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
#!/usr/bin/env bash
2+
3+
# Copyright 2024 MongoDB Inc
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
#
18+
# Shell script to generate the Terraform documentation for the resource and data sources.
19+
#
20+
# Usage: ./generate-doc.sh" ${resource_name}
21+
# resource_name is the terraform resource name. Example: search_deployment
22+
# echo "Examples:"
23+
# echo " search_deployment"
24+
# echo " project"
25+
# echo " online_archive"
26+
# echo " encryption_at_rest"
27+
#
28+
# The scripts requires to install tfplugindocs and to create the resource templates in
29+
# templates/resources/${resource_name}.html.markdown.tmpl and
30+
# templates/data-sources/${resource_name}.html.markdown.tmpl
31+
# templates/data-sources/${resource_name}s.html.markdown.tmpl
32+
33+
set -euo pipefail
34+
35+
TF_VERSION="${TF_VERSION:-"1.6"}" # TF version to use when running tfplugindocs. Default: 1.6.6
36+
TEMPLATE_FOLDER_PATH="${TEMPLATE_FOLDER_PATH:-"templates"}" # PATH to the templates folder. Default: templates
37+
38+
39+
# if [ -z "${resource_name}" ]; then
40+
if [ $# -eq 0 ]; then
41+
echo "Error: Input param not found"
42+
echo "Usage: ./generate-doc.sh resource_name"
43+
echo "resource_name is the terraform resource and data source name."
44+
echo "Examples:"
45+
echo " search_deployment"
46+
echo " project"
47+
echo " online_archive"
48+
echo " encryption_at_rest"
49+
exit 1
50+
fi
51+
52+
resource_name="$1"
53+
54+
if [ ! -f "${TEMPLATE_FOLDER_PATH}/resources/${resource_name}.html.markdown.tmpl" ]; then
55+
echo "Error: we coudn't find the template for the ${resource_name} resource"
56+
echo "Please, make sure to include the resource template under ${TEMPLATE_FOLDER_PATH}/resources/${resource_name}.html.markdown.tmpl"
57+
exit 1
58+
fi
59+
60+
if [ ! -f "${TEMPLATE_FOLDER_PATH}/data-sources/${resource_name}.html.markdown.tmpl" ]; then
61+
echo "Error: we coudn't find the template for the ${resource_name} data source"
62+
echo "Please, make sure to include the data source template under ${TEMPLATE_FOLDER_PATH}/data-sources/${resource_name}.html.markdown.tmpl"
63+
exit 1
64+
fi
65+
66+
if [ ! -f "${TEMPLATE_FOLDER_PATH}/data-sources/${resource_name}s.html.markdown.tmpl" ]; then
67+
echo "Warning: we coudn't find the template for the ${resource_name}s data source"
68+
echo "Please, make sure to include the data source template under ${TEMPLATE_FOLDER_PATH}/data-sources/${resource_name}.html.markdown.tmpl"
69+
printf "Skipping this check: We assume that the resource does not have a plural data source.\n\n"
70+
fi
71+
72+
# tfplugindocs uses this folder to generate the documentations
73+
mkdir -p docs
74+
75+
tfplugindocs generate --tf-version "${TF_VERSION}" --website-source-dir "${TEMPLATE_FOLDER_PATH}"
76+
77+
if [ ! -f "docs/resources/${resource_name}.html.markdown" ]; then
78+
echo "Error: We cannot find the documentation file for the resource ${resource_name}.html.markdown"
79+
echo "Please, make sure to include the resource template under templates/resources/${resource_name}.html.markdown.tmpl"
80+
exit 1
81+
else
82+
printf "\nMoving the generated file %s.html.markdown to the website folder" "${resource_name}"
83+
mv "docs/resources/${resource_name}.html.markdown" "website/docs/r/${resource_name}.html.markdown"
84+
fi
85+
86+
if [ ! -f "docs/data-sources/${resource_name}.html.markdown" ]; then
87+
echo "Error: We cannot find the documentation file for the data source ${resource_name}.html.markdown"
88+
echo "Please, make sure to include the data source template under templates/data-sources/${resource_name}.html.markdown.tmpl"
89+
exit 1
90+
else
91+
printf "\nMoving the generated file %s.html.markdown to the website folder" "${resource_name}"
92+
mv "docs/data-sources/${resource_name}.html.markdown" "website/docs/d/${resource_name}.html.markdown"
93+
fi
94+
95+
if [ ! -f "docs/data-sources/${resource_name}s.html.markdown" ]; then
96+
echo "Warning: We cannot find the documentation file for the data source ${resource_name}s.html.markdown."
97+
echo "Please, make sure to include the data source template under templates/data-sources/${resource_name}s.html.markdown.tmpl"
98+
printf "Skipping this step: We assume that the resource does not have a plural data source.\n\n"
99+
else
100+
printf "\nMoving the generated file %s.html.markdown to the website folder" "${resource_name}s"
101+
mv "docs/data-sources/${resource_name}s.html.markdown" "/website/docs/d/${resource_name}s.html.markdown"
102+
fi
103+
104+
# Delete the docs/ folder
105+
rm -R docs/
106+
107+
printf "\nThe documentation for %s has been created.\n" "${resource_name}"

‎templates/data-sources/search_deployment.html.markdown.tmpl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ description: |-
1111
{{ .Description | trimspace }}
1212

1313
## Example Usages
14-
{{ tffile (printf "examples/{{.Name}}/main.tf")}}
14+
{{ tffile (printf "examples/%s/main.tf" .Name )}}
1515

1616
{{ .SchemaMarkdown | trimspace }}
1717

‎templates/resources/search_deployment.html.markdown.tmpl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ description: |-
1212

1313
## Example Usages
1414

15-
{{ tffile (printf "examples/{{.Name}}/main.tf")}}
15+
{{ tffile (printf "examples/%s/main.tf" .Name )}}
1616

1717
{{ .SchemaMarkdown | trimspace }}
1818

0 commit comments

Comments
 (0)