If you have ever worked with Ansible, it’s almost a guarantee that you have used their online docs to figure out what parameters a given module supports, how they should be used, or what their defaults are. Over the past few weeks, I’ve been working on a few custom modules and was trying to find a way to generate web docs for them, and have them locally accessible or easily posted to GitHub.
Ansible offers a way to “make webdocs,” but it generates the complete module inventory and truth be told, I didn’t get this work for my custom modules, so I figured I would explore a “simplified” way --- a way that should be able to generate docs as needed for one or more modules on an as needed basis.
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.
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.
There are three main areas to cover about this playbook. (1) vars (2) obtaining the docs and (3) creating the markdown file.
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.
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.
Sample 1
Sample 2
Sample 3
Because my blog platform lacks significant features, I can’t post the markdown or full output here. To see the full detail, check it out on GitHub.
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.
Since everything has been posted to GitHub, feel free to download the example playbook, template, and the ansible_docstring module to try it out. There are likely some error checks that could be improved, so if you want to contribute, open an issue or pull request!
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
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
RSS Feed
