forked from jboss-openshift/application-templates
/
gen_template_docs.py
executable file
·252 lines (218 loc) · 10.9 KB
/
gen_template_docs.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
#!/usr/bin/env python
# gen_template_doc.py
# Kyle Liberti <kliberti@redhat.com>, Jonathan Dowland <jdowland@redhat.com>
# ver: Python 3
# Desc: Generates application-template documentation by cloning application-template
# repository, then translating information from template JSON files into
# template asciidoctor files, and stores them in the a directory(Specified by
# TEMPLATE_DOCS variable).
#
# Notes: NEEDS TO BE CLEANED UP
import json
import os
import sys
from ptemplate.template import Template
GIT_REPO = "https://github.com/jboss-openshift/application-templates.git"
REPO_NAME = "application-templates/"
TEMPLATE_DOCS = "docs/"
APPLICATION_DIRECTORIES = ("amq","eap","webserver")
ignore_dirs = ['docs', '.git']
LINKS = {"jboss-eap6-openshift:${EAP_RELEASE}": "../../eap/eap-openshift{outfilesuffix}[`jboss-eap-6/eap-openshift`]", \
"jboss-webserver3-tomcat7-openshift:${JWS_RELEASE}": "../../webserver/tomcat7-openshift{outfilesuffix}[`jboss-webserver/tomcat7-openshift`]", \
"jboss-webserver3-tomcat8-openshift:${JWS_RELEASE}": "../../webserver/tomcat8-openshift{outfilesuffix}[`jboss-webserver/tomcat8-openshift`]"};
PARAMETER_VALUES = {"APPLICATION_HOSTNAME": "secure-app.test.router.default.local", \
"GIT_URI": "`https://github.com/jboss-openshift/openshift-examples.git", \
"GIT_REF": "master", \
"GIT_CONTEXT_DIR": "helloworld", \
"GITHUB_TRIGGER_SECRET": "secret101", \
"GENERIC_TRIGGER_SECRET": "secret101"}
autogen_warning="""////
AUTOGENERATED FILE - this file was generated via ./gen_template_docs.py.
Changes to .adoc or HTML files may be overwritten! Please change the
generator or the input template (./*.in)
////
"""
def generate_templates():
for directory in set(os.listdir('.')) - set(ignore_dirs):
if not os.path.isdir(directory):
continue
if not os.path.exists(TEMPLATE_DOCS + directory):
os.makedirs(TEMPLATE_DOCS + directory)
for template in os.listdir(directory):
# skip editor temp files
if template[-4:] == '.swp':
continue
with open(directory + "/" + template) as data_file:
data = json.load(data_file)
if not 'labels' in data or not "template" in data["labels"]:
sys.stderr.write("no template label for template %s, can't generate documentation\n"%\
(directory + "/" + template))
continue
template_doc = TEMPLATE_DOCS + directory + "/" + data["labels"]["template"] + ".adoc"
with open(template_doc, "w") as text_file:
text_file.write(autogen_warning)
text_file.write(createTemplate(data, directory, template))
def createTemplate(data, directory, template_file):
templater = Template()
templater.template = open('./template.adoc.in').read()
tdata = { "template": data['labels']['template'], }
# Fill in the template description, if supplied
if 'annotations' in data['metadata'] and 'description' in data['metadata']['annotations']:
tdata['description'] = data['metadata']['annotations']['description']
# Fill in template parameters table, if there are any
if ("parameters" in data and "objects" in data) and len(data["parameters"]) > 0:
tdata['parameters'] = [{ 'parametertable': createParameterTable(data) }]
if "objects" in data:
tdata['objects'] = [{}]
# Fill in sections if they are present in the JSON (createObjectTable version)
for kind in ['Service', 'Route', 'BuildConfig', 'PersistentVolumeClaim']:
if 0 >= len([ x for x in data["objects"] if kind == x["kind"] ]):
continue
tdata['objects'][0][kind] = [{ "table": createObjectTable(data, kind) }]
# Fill in sections if they are present in the JSON (createContainerTable version)
for kind in ['image', 'readinessProbe', 'ports', 'env']:
if 0 >= len([obj for obj in data["objects"] if obj["kind"] == "DeploymentConfig"]):
continue
tdata['objects'][0][kind] = [{ "table": createContainerTable(data, kind) }]
# Fill in sections if they are present in the JSON (createDeployConfigTable version)
for kind in ['triggers', 'replicas', 'volumes', 'serviceAccount']:
if 0 >= len([obj for obj in data["objects"] if obj["kind"] == "DeploymentConfig"]):
continue
tdata['objects'][0][kind] = [{ "table": createDeployConfigTable(data, kind) }]
# the 'secrets' section is not relevant to the secrets templates
if "secrets" != directory:
tdata['objects'][0]['secrets'] = [{ "templateabbrev": data['labels']['template'][0:3] }]
# currently the clustering section applies only to EAP templates
if "eap" == directory:
tdata['objects'][0]['clustering'] = [{}]
return templater.render(tdata)
def buildRow(columns):
return ("\n|" + " | ".join([" `" + col + "` " for col in columns])).replace("`--`", "--")
def getVolumePurpose(name):
name = name.split("-")
if("certificate" in name or "keystore" in name or "secret" in name):
return "ssl certs"
elif("amq" in name):
return "kahadb"
elif("pvol" in name):
return name[1]
else:
return "--"
# Used for getting image enviorment variables into parameters table and parameter
# descriptions into image environment table
def getVariableInfo(data, name, value):
for d in data:
if(d["name"] == name or name[1:] in d["name"] or d["name"][1:] in name):
return d[value]
if(value == "value" and name in PARAMETER_VALUES.keys()):
return PARAMETER_VALUES[name]
else:
return "--"
def createParameterTable(data):
text = ""
for param in data["parameters"]:
deploy = [d["spec"]["template"]["spec"]["containers"][0]["env"] for d in data["objects"] if d["kind"] == "DeploymentConfig"]
environment = [item for sublist in deploy for item in sublist]
envVar = getVariableInfo(environment, param["name"], "name")
value = param["value"] if param.get("value") else getVariableInfo(environment, param["name"], "value")
columns = [param["name"], envVar, param["description"], value, param["required"]]
text += buildRow(columns)
return text
def createObjectTable(data, tableKind):
text = ""
columns =[]
for obj in data["objects"]:
if obj["kind"] == 'Service' and tableKind == 'Service':
columns = [obj["metadata"]["name"], str(obj["spec"]["ports"][0]["port"]), obj["metadata"]["annotations"]["description"] ]
elif obj["kind"] == 'Route' and tableKind == 'Route':
if(obj["spec"].get("tls")):
columns = [obj["id"], ("TLS "+ obj["spec"]["tls"]["termination"]), obj["spec"]["host"]]
else:
columns = [obj["id"], "none", obj["spec"]["host"]]
elif obj["kind"] == 'BuildConfig' and tableKind == 'BuildConfig':
sti = obj["spec"]["strategy"]["sourceStrategy"]["from"]["name"]
columns = [sti," link:" + LINKS[sti], obj["spec"]["output"]["to"]["name"], ", ".join({x["type"] for x in obj["spec"]["triggers"] }) ]
elif obj["kind"] == 'PersistentVolumeClaim' and tableKind == 'PersistentVolumeClaim':
columns = [obj["metadata"]["name"], obj["spec"]["accessModes"][0]]
if(obj["kind"] == tableKind):
text += buildRow(columns)
return text
def createDeployConfigTable(data, table):
text = ""
deploymentConfig = (obj for obj in data["objects"] if obj["kind"] == "DeploymentConfig")
for obj in deploymentConfig:
columns = []
deployment = obj["metadata"]["name"]
spec = obj["spec"]
template = spec["template"]["spec"]
if(template.get(table) or spec.get(table)):
if table == "triggers":
columns = [deployment, spec["triggers"][0]["type"] ]
elif table == "replicas":
columns = [deployment, str(spec["replicas"]) ]
elif table == "serviceAccount":
columns = [deployment, template["serviceAccount"]]
elif table == "volumes":
volumeMount = obj["spec"]["template"]["spec"]["containers"][0]["volumeMounts"][0]
name = template["volumes"][0]["name"]
readOnly = str(volumeMount["readOnly"]) if "readOnly" in volumeMount else "false"
columns = [deployment, name, volumeMount["mountPath"], getVolumePurpose(name), readOnly]
text += buildRow(columns)
return text
def createContainerTable(data, table):
text = ""
deploymentConfig = (obj for obj in data["objects"] if obj["kind"] == "DeploymentConfig")
for obj in deploymentConfig:
columns = []
deployment = obj["metadata"]["name"]
container = obj["spec"]["template"]["spec"]["containers"][0]
if table == "image":
columns = [deployment, container["image"]]
text += buildRow(columns)
elif table == "readinessProbe": #abstract out
if container.get("readinessProbe"):
text += ("\n." + deployment + "\n----\n" \
+ " ".join(container["readinessProbe"]["exec"]["command"]) \
+ "\n----\n")
elif table == "ports":
text += "\n." + str(len(container["ports"])) + "+| `" + deployment + "`"
ports = container["ports"]
for p in ports:
columns = ["name", "containerPort", "protocol"]
columns = [str(p[col]) if p.get(col) else "--" for col in columns]
text += buildRow(columns)
elif table == "env":
environment = container["env"]
text += "\n." + str(len(environment)) + "+| `" + deployment + "`"
for env in environment:
columns = [env["name"], getVariableInfo(data["parameters"], env["name"], "description")]
# TODO: handle valueFrom instead of value
if "value" in env:
columns.append(env["value"])
else:
columns.append("--")
text += buildRow(columns)
return text
fullname = {
"amq": "JBoss A-MQ",
"eap": "JBoss EAP",
"webserver": "JBoss Web Server"
}
def generate_index():
"""Generates an index page for the template documentation."""
with open('docs/index.adoc','w') as fh:
fh.write(autogen_warning)
# page header
fh.write(open('./index.adoc.in').read())
for directory in set(os.listdir('.')) - set(ignore_dirs):
if not os.path.isdir(directory):
continue
# section header
fh.write('\n== %s\n\n' % fullname.get(directory, directory))
# links
for template in [ os.path.splitext(x)[0] for x in os.listdir(directory) ]:
fh.write("* link:./%s/%s.adoc[%s]\n" % (directory, template, template))
if __name__ == "__main__":
# expects to be run from the root of the repository
generate_templates()
generate_index()