The outcome was the creation of an Ansible module and Jinja2 template that automatically generates a markdown file (that can then be viewed or posted anywhere).
How does it work?
The modules you’ve built or are local to your machine (even Ansible core modules) that you want to generate a web doc for must be documented according to Ansible standards. That’s the only major requirement.
From there, you create a playbook that’ll generate the required markdown document.
Here is a sample playbook that generates a markdown doc for the Ansible files modules.
Three variables can optionally be defined (heading, subheading, and requirements) that would then be displayed when the markdown doc is generated.
The first task uses the new custom module called ansible_docstring. This module gathers the appropriate module documentation and examples from all modules in a given directory. These docs and examples are then stored in a new variable called modules.
The second task then generates the final markdown doc based on the new Jinja2 template.
In order to get started, just make sure you have Ansible installed, do a git clone of the repo, and execute the playbook. You’ll then need a way of viewing the markdown file in a web browser if you aren’t using GitHub.
Sound easy enough?
Below are a few screen shots of what the playbook generates. To see the actual thing, check it out here.
Note: it’s not shown in this post, but the playbook is generating a markdown file and then I was previewing the markdown in HTML using a markdown viewer plugin for Sublime Text 3. Following that, I then just uploaded the created markdown file to GitHub.
On a side note, if I didn't end up creating this, I would have spent a ton of time manually creating tables in markdown one at a time for each module I was building! And just imagine making a small change like adding a row or column to each one!
Happy Documenting!
Thanks,
Jason
Twitter: @jedelman8