Convert YAML file to text/html table for documentation
Time to time I needed to document YAML files for end-users. And best way so far we have seen is to build table and put each field in table row and document it. I need a quick script that will take YAML file and generated (html) table; only thing I needed to do was to input some help text that explains field
Above need gave way to this python script; it will do just that - given input (yaml) file it will
it iterates over each yaml section and builds table(s) out of it
As of now it creates multiple tables based on top level YAML sections
This mainly uses two python libraries 'pyaml' and 'prettyTable'
PYAML: For reading the yaml file
PrettyTable: For printing text tables or HTML table
** Note ** : In this script I actually used oyaml as it preserves order in python dictionary
For field description, it will just generate random Lorem ipsum one-liner text using python library loremipsum
> python yaml_to_table.py -h
usage: yaml_to_table.py [-h] --inputFile INPUTFILE [--out {txt,html,text}]
YAML file to (HTML) table converter
optional arguments:
-h, --help show this help message and exit
--inputFile INPUTFILE
input yaml file to process
--out {txt,html,text}
convert yaml to text table or html table
text table will be printed as STDOUT - html table will be save in html fileLet's take an example of simple kubernetes deployment file (as show below)
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
labels:
app: nginx
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.7.9
ports:
- containerPort: 80If you run script with this command :
python yaml_to_table.py --inputFile samples/k8sDeploy.yaml --out textYou will see output like this
=> apiVersion:
+------------+---------------+----------+--------------+
| Field | Example Value | Required | Description |
+------------+---------------+----------+--------------+
| apiVersion | apps/v1 | | Lorem ipsum. |
+------------+---------------+----------+--------------+
Raw yaml:
apiVersion: apps/v1
=> kind:
+-------+---------------+----------+------------------------+
| Field | Example Value | Required | Description |
+-------+---------------+----------+------------------------+
| kind | Deployment | | Lorem ipsum dolor sit. |
+-------+---------------+----------+------------------------+
Raw yaml:
kind: Deployment
=> metadata:
+--------+------------------+----------+--------------------------------------------------------------------------------------+
| Field | Example Value | Required | Description |
+--------+------------------+----------+--------------------------------------------------------------------------------------+
| name | nginx-deployment | | Lorem ipsum dolor sit amet, consecteteur adipiscing elit b'nunc' b'id' b'eu'. |
| labels | | | Lorem ipsum dolor sit amet, consecteteur adipiscing elit b'duis' b'eu' b'id' b'sit'. |
| app | nginx | | Lorem ipsum dolor sit amet, consecteteur adipiscing. |
+--------+------------------+----------+--------------------------------------------------------------------------------------+
Raw yaml:
metadata:
name: nginx-deployment
labels:
app: nginx
=> spec:
+---------------------------+---------------+----------+---------------------------------------------------------------------------------------------------+
| Field | Example Value | Required | Description |
+---------------------------+---------------+----------+---------------------------------------------------------------------------------------------------+
| replicas | 3 | | Lorem ipsum. |
| selector | | | Lorem ipsum. |
| matchLabels | | | Lorem ipsum dolor sit amet, consecteteur adipiscing elit b'arcu' b'id' b'ad' b'neque' b'a' b'eu'. |
| app | nginx | | Lorem ipsum. |
| template | | | Lorem ipsum dolor sit amet, consecteteur. |
| metadata | | | Lorem ipsum dolor sit amet. |
| labels | | | Lorem ipsum dolor sit amet, consecteteur adipiscing. |
| app | nginx | | Lorem ipsum dolor sit amet, consecteteur adipiscing elit b'diam' b'et'. |
| spec | | | Lorem ipsum dolor sit. |
| containers | | | Lorem ipsum dolor sit amet, consecteteur adipiscing elit b'quis'. |
| name | nginx | | Lorem ipsum. |
| image | nginx:1.7.9 | | Lorem ipsum dolor sit. |
| ports | | | Lorem ipsum dolor sit amet, consecteteur. |
| containerPort | 80 | | Lorem ipsum dolor sit amet, consecteteur adipiscing elit. |
+---------------------------+---------------+----------+---------------------------------------------------------------------------------------------------+
Raw yaml:
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.7.9
ports:
- containerPort: 80
If I need html as output then I can run it like this
> python yaml_to_table.py --inputFile samples/k8sDeploy.yaml --out html
File samples/k8sDeploy.doc.html has been generatedTool will generate output HTML file that will look like this :
You can just copy the body part of HTML and copy it to JIRA/Confluence as show below
