Module self documentation thoughts.

Archives Ansible Project
1

Reading through the module sources, sometimes one has to dig a bit to
learn about the options.

I really appreciate the language-agnostic approach, but wonder if the
module spec should recommend a very minimalist documentation standard,
like:

1. If passed a magic argument, tersely show function and options
(<modulename> -a document=True maybe?).

2. Failing that, a good top of module comment stating function and
options.

The first option would let us automate documentation generation of
contributations. Most editors could be set up to show quick help on a
module name under the cursor.

--Brad

2

This is mostly already covered by the web documentation: http://ansible.github.com/modules.html

I strongly believe web documentation can explain things better and allow for formatting and in depth examples,
and not all just in one page. Keeping restructured text inline with the source code would feel weird, IMHO.

For updates to the docs, submit a pull request to:

https://github.com/ansible/ansible.github.com/tree/master/rst

–Michael

3

Michael,

I strongly believe web documentation can explain things better and allow for formatting and in depth examples,
and not all just in one page. Keeping restructured text inline with the source code would feel weird, IMHO.

I prefer web docs too, but--to press back a bit, The Sphinx way--
putting api and core docs in the code, adding prose and structure in
rst outside the code--seems to be working well for a lot of projects,
including Jinja and Python's libraries. Granted, it still needs good
leadership to stay clear and simple, and if markup in doc strings
feels unfamiliar, well, it will feel unfamiliar.

Hope you'll reconsider, meanwhile, thanks for the link:

For updates to the docs, submit a pull request to:
https://github.com/ansible/ansible.github.com/tree/master/rst

--Brad

4

FYI – Ansible doesn’t use docstrings from code to generate the docs project at all, everything is self contained in the rst/ directory of the docs
project, so you don’t need to know Python to work on the docs.

I will be keeping things this way.