Everything as code, autogenerated Markdown documentation with Gomplate.

These days, where the “everything as code” paradigm is pretty much everywhere in the information technology world, infrastructure, containers and applications are configured and deployed usually via declarative tools (Terraform, Ansible, Helm) making the development and deployment consistent and repeatable. However, somewhere where the automate all the things has not made the cut is the documentation in general. People usually argue that documentation is boring and therefore this vital and crucial piece of work is usually neglected. Years ago I came across terraform-docs which has the capability to generate a markdown file from terraform variables, that’s quite cool but it’s pretty much Terraform specific. Back last year I came across Gomplate a tool written in Golang capable to render any data input to an output using templates. From its website “gomplate is a template renderer which supports a growing list of datasources, such as: JSON (including EJSON - encrypted JSON), YAML, AWS EC2 metadata, BoltDB, Hashicorp Consul and Hashicorp Vault secrets.” Hence i started to delve into Gomplate and its reach features which they were well suited for generating README Markdown files in an automated fashion.

Requirements:

Git
Gomplate - brew install gomplate

For convenience I have put a basic example into this repository - https://github.com/p0bailey/blog-examples/tree/main/gomplate/markdown

A list of variable is present at: https://github.com/p0bailey/blog-examples/blob/main/gomplate/markdown/env

env file

cat env
PROJECT_NAME=My super-duper project
PROJECT_URL=www.example-super-duper.org
PROJECT_DESCRIPTION="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc faucibus viverra mollis."

A Template to be rendered: https://github.com/p0bailey/blog-examples/tree/main/gomplate/markdown/templates

# {{env.Getenv "PROJECT_NAME" }}

Project website: {{env.Getenv "PROJECT_URL" }}

Project description: {{env.Getenv "PROJECT_DESCRIPTION" }}

Updated by: {{.Env.USER}} at '{{ ((time.Now)).Format "Mon Jan 2 15:04:05 MST 2006" }}'

In the template there are two additional variables:

Exposes the os.Getenv function. https://docs.gomplate.ca/functions/env/

’{{ ((time.Now)).Format “Mon Jan 2 15:04:05 MST 2006” }}’

This namespace wraps Go’s time package, and a few of the functions return a time https://docs.gomplate.ca/functions/time/

A Makefile to ease the automation: https://github.com/p0bailey/blog-examples/blob/main/gomplate/markdown/Makefile

Clone the repo:

git clone https://github.com/p0bailey/blog-examples.git

cd blog-examples/gomplate/markdown/

Run:

 make template

cat README.md

And there you go! Your README has been automatically generated with system and user defined variables.

README.md

Project website: www.example-super-duper.org

Project description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc faucibus viverra mollis."

Updated by: phillip at 'Sun Oct 11 15:43:22 BST 2020'

In this post I have just scratched the surface on what is possible with Gomplate. Definitely I’m going to write a series of instalments covering Gomplate across different domains.

Stay tuned,

Phillip