Little did I know, when I suggested to Michael DeHaan in a personal e-mail that I create a kind of reference card for Ansible, that it would turn into “real” work. :-)

The two reference cards I’ve previously created (one for CouchDB, and the other for DNSSEC) have been pretty successful judging by the number of times they’ve been downloaded, but this time around, I wanted to make sure to automate things as much as possible. (No fiddling in getting boxes aligned in OmniGraffle, etc.) Another requirement I had was that output should be produced with LaTeX because of the excellent experience I had while writing my book. However, not being proficient enough in LaTeX to create a new style, I took the liberty of asking the guys who created the Grml ZSH reference whether I could use their pleasing layout to get started with: they granted permission for me to do so.

I believe it was I who suggested (on IRC) to create documentation within individual Ansible modules in order to generate LaTeX code from those. One thing led to another, and we’ve finally settled on a method which is extensible and flexible.

To cut a long story short, each module will have a DOCUMENTATION string in it with a YAML dict describing the module, it’s name, options, etc. Here’s a condensed version:

DOCUMENTATION = '''
---
module: get_url
short_description: Downloads files from HTTP, HTTPS, or FTP to node
description:
     - Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote
       server must have direct access to the remote resource.
version_added: "0.6"
options:
  - url:
      description:
        - HTTP, HTTPS, or FTP URL
      required: true
      default: null
      aliases: []
  - dest:
      description:
        - absolute path of where to download the file to.
        - If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, I(thirsty=yes) must also be set.
      required: true
      default: null
'''

Thanks to Peter van Dijk who wrote four vital lines of code for me, I can use Python’s ast module to grab that string out of module files and carry on from there. My mofo (module formatter; maybe I need to change the name …? ;-) uses Jinja2 templates to generate LaTeX for inclusion in the reference card, rudimentary HTML and source for Unix man pages. This is what the LaTeX output currently looks like for the DOCUMENTATION string above:

I had to “invent” a kind of markup in order to be able to use emphasis, etc. Michael dreaded the thought of using Markdown or rST (which I can understand), and I plainly refused to use HTML markup, so I came to a simple function-call type of solution using e.g. I() which I can easily (cough) parse with a regular expresion in a custom Jinja2 filter.

I’m still working on this, but you can have a sneak peek at the document as it currently stands. Note that only a fraction of Ansible’s modules are in the PDF because the majority still needs documenting as per our new “standard”. Want to help? Please do!

I’d appreciate contributions to the booklet as well: ideas, text, whatever. Submit an “issue” or even better, a “pull request” on Github.