Hello,
as you may have gathered (particularly if you've been following issue
#991 on Github 
we're settling on DOCUMENTATION strings for modules.
I believe I'm the one who started all this, so I'd like to update you
with what's been done so far, if I may, hoping we can surprise Michael
(who's currently AWOL I believe) with completed module documentation
when he returns. #wishfulthinkingmaybe #crossesfingers
We've agreed to add a DOCUMENTATION string to modules from which we can
generate a module's, documentation. I think Michael wants this for the
ansible-commander UI, and I want this for the booklet (a.k.a. reference
card) I'm wanting to create for Ansible. Other uses could be generation
of static documentation pages (and maybe even Ansible documentation as
an .epub or .mobi?)
An example taken from the `lineinfile' module I documented yesterday
(pull-request already submitted):
> DOCUMENTATION = '''
> ---
> module: lineinfile
> author: Daniel Hokka Zakrisson
> short_description: Ensure a particular line is in a file
> description:
> - This module will search a file for a line, and ensure that it is present or absent.
> - This is primarily useful when you want to change a single line in a
> file only. For other cases, see the M(copy) or M(template) modules.
> version_added: "0.7"
> options:
> - regexp:
> required: true
> description:
> - The regular expression to look for in the file. For I(state=present),
> the pattern to replace. For I(state=absent), the pattern of the line
> to remove.
> examples:
> - code: lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
> - code: lineinfile name=/etc/sudoers state=absent regexp="^%wheel"
> '''
This YAML format allows us to produce reasonably good looking output for
several different formats, using a small program and a bunch of Jinja2
templates. (My intention was to use stuff required for Ansible anyway.)
(The get_url, raw, setup, and a bit of the file modules are documented,
with `get_url' currently containing most of the tags we've settled on;
these are in PR #1063 [3].)
The reference card (which started this whole thing rolling), a.k.a. the
"booklet" is making progres, if slowly. Aside from $DAYJOB, the delay
has been due to the fact that we've spent some time on settling on the
DOCUMENTATION format.
A utility called `mofo' (MOdule FOrmatter; hmm: maybe I should change the
name...) currently parses DOCUMENTATION from Ansible's modules in `library/',
extracts the YAML, and uses Jinja2 templates to generate:
* LaTeX source (which I include in main .tex)
* man page source (nroff/troff)
* HTML (barely started)
A few notes on the above YAML and the `mofo' utility:
* I've added an optional `author' which currently finds its way into the
man pages if it's defined.
* Supports generation of man pages; example in man(1) format with
corresponding PDF output is included.
* Creates boilerplate DOCUMENTATION string on demand (-G)
The whole lot can currently be found at [1]. Please do glance at a
man-page and an early preview PDF of the booklet [2], if you can spare
some time.
I'd appreciate your comments and lots of pull requests (both for booklet
content as well as for module DOCUMENTATION).
Best regards,
-JP
[1]: https://github.com/jpmens/ansible-booklet
[2]: https://github.com/downloads/jpmens/ansible-booklet/ansible-booklet.pdf
[3]: https://github.com/ansible/ansible/pull/1063