Ansible modules documentation

Archives Ansible Project
1

Hi guy,
  I'm working on automatic docs generator for Ansible (HTML, e-pub,
HTML, ..), but I find some "inconsistencies", before start to fix it
and send pull request I ask to you what do you think about change
proposal.

# Description
-- Status
Description is an list of string, but sometime I found it is a string
(eg: cron, gem, uri, vagrant, ..)

-- Proposal
Change all description to be a list (Pull reqest 2528 ¹)

-- Workaround
Each docs generator require to add a if condition to check if data is
a string or array, ..

# Version added
-- Status
Version added in documentation sometime is a number, sometime is a
string (eg: string in assemble, nuber in nagios) . This can generate
"error" in parsing.

-- Proposal
Change all items to be string (quote escaped), all version require to have:
  MAIN.MINOR.PATCH
maybe we can limit to MAIN.MINOR, but the first releases are 0.0.2, ..
so we can change to "lost" this information and use minor version the
only possible version-change that can add a module.

-- Workaround
Cast data to string before manage this informations and normalize data
before parsing.

# Examples
-- Status
Documentation have two different point to insert examples, the first
is the item examples in DOCUMENTATION. This is a list of items with
code and description.
In some other case there are EXAMPLES that contains a "blob" of data.
I think this is a "historic heritage".

-- Proposal
Move EXAMPLES information in DOCUMENTATION/examples or
DOCUMENTATION/note (eg data in mysql_user is note and not code
example, have code and documentation, ...) and remove EXAMPLES items.

-- Workaround
Manage examples and EXAMPLES in different way, generating
"inconsistent" docs interface.

# Indentation
-- Status
Some data in DOCUMENTATION have 2 space as indentation, some other have 4 space.

-- Proposal
Move all to have 2 space indentation.

-- Workaround
Actually not required, the python parser automatically fix this. I
suggest to normalize as "coding standard" request and not "data
management" error.

Have a great Easter

Bye
       Marco

¹ https://github.com/ansible/ansible/pull/2528

2

Replies inline

Hi guy,
  I'm working on automatic docs generator for Ansible (HTML, e-pub,
HTML, ..), but I find some "inconsistencies", before start to fix it
and send pull request I ask to you what do you think about change
proposal.

# Description
-- Status
Description is an list of string, but sometime I found it is a string
(eg: cron, gem, uri, vagrant, ..)

I am fine with making it always be a list of strings, because the list
was intended to be for paragraphs.

-- Proposal
Change all description to be a list (Pull reqest 2528 ¹)

+1

-- Workaround
Each docs generator require to add a if condition to check if data is
a string or array, ..

YES!

# Version added
-- Status
Version added in documentation sometime is a number, sometime is a
string (eg: string in assemble, nuber in nagios) . This can generate
"error" in parsing.

Suggest it be a string, since it is a release version.

The documentation generator should cast it so it wouldn't matter.

-- Proposal
Change all items to be string (quote escaped), all version require to have:
  MAIN.MINOR.PATCH
maybe we can limit to MAIN.MINOR, but the first releases are 0.0.2, ..
so we can change to "lost" this information and use minor version the
only possible version-change that can add a module.

I'm fine with removing an field that says it was added back then,
since it's ancient, but version number sorting is not the same as a
numeric sort.

-- Workaround
Cast data to string before manage this informations and normalize data
before parsing.

# Examples
-- Status
Documentation have two different point to insert examples, the first
is the item examples in DOCUMENTATION. This is a list of items with
code and description.
In some other case there are EXAMPLES that contains a "blob" of data.
I think this is a "historic heritage".

-- Proposal
Move EXAMPLES information in DOCUMENTATION/examples or
DOCUMENTATION/note (eg data in mysql_user is note and not code
example, have code and documentation, ...) and remove EXAMPLES items.

Nope, we move everything to EXAMPLES.

It's a pain in the ass to put examples of playbooks nested inside the
YAML string, so EXAMPLES is the way to go everywhere.

Some data in DOCUMENTATION have 2 space as indentation, some other have 4 space.

Shouldn't matter for YAML data, I don't think. 2 space is reasonable
if we just want to be organized.

-- Proposal
Move all to have 2 space indentation.

-- Workaround
Actually not required, the python parser automatically fix this. I
suggest to normalize as "coding standard" request and not "data
management" error.

Have a great Easter

Absolutely, you too!

3

Sorry, I'm not agree, having all example in a unique block of code
can't be not easy to manipulate, we can have more then one example
(much module have a lot of examples) and we can't split it.
I think convert (and mantains) module example inside DOCUMENTATION
can't be a pain in the ass, eg, from gem module:

----8<--------8<--------8<--------8<--------8<--------8<--------8<----
EXAMPLES = '''
# Installs version 1.0 of vagrant.
gem: name=vagrant version=1.0 state=present

# Installs latest available version of rake.
gem: name=rake state=latest

# Installs rake version 1.0 from a local gem on disk.
gem: name=rake gem_source=/path/to/gems/rake-1.0.gem state=present
'''
----8<--------8<--------8<--------8<--------8<--------8<--------8<----

need to be converted in:

----8<--------8<--------8<--------8<--------8<--------8<--------8<----
DOCUMENTATION = '''

4

Sorry, I'm not agree, having all example in a unique block of code
can't be not easy to manipulate, we can have more then one example
(much module have a lot of examples) and we can't split it.
I think convert (and mantains) module example inside DOCUMENTATION
can't be a pain in the ass, eg, from gem module:

It's already easy to manipulate. That's why we have functions to
parse this already in utils.

Playbook examples (YAML embedded into YAML) are quite impossible to
work with and I always have to fix syntax on pull requests.

This saves me a manual step that I have to do *every single time* I
get a pull request to the module doc and I'm simply not going to keep
copy-pasting everything into YAMLlint.com each time. It is also
immensely frustrating for users trying to figure out how to embed YAML
in YAML correctly either.

The one line examples are one thing, try to embed a playbook inside
the DOCUMENTATION string and you will go insane pretty quickly.

5

Thanks for reply Michael, I don't discuss your effort on maintains
docs in modules and I will adapt what do you (project leader :smiley: )
define as the right way to manage doc/example.

Main point of discussion IMHO are:
* One unique point to read examples.
* Examples need to be a list of example.
* Example need to be structured (code/description).

I'm not discussing do move example out of DOCUMENTATION to EXAMPLES.

Why I propose this structure? I think that have different entry point
in docs can be "a problem" when parsing docs, EXAMPLES is "not
structurated" string, so we can't manage (from doc generator)
different example. Some module report YAML code in DOCUMENTATION block
and I think don't make this information less readable, eg: ec2_vol:

DOCUMENTATION='''
# ...
examples:
   - code: 'local_action: ec2_vol instance=XXXXXX volume_size=5 device_name=sdd'
     description: "Simple playbook example"
   - code: |
            - name: Launch instances
              local_action: ec2 keypair=$keypair image=$image wait=yes count=3
              register: ec2
            - name: Create volumes and attach
              local_action: ec2_vol instance=${item.id} volume_size=5
              with_items: ${ec2.instances}
              register: ec2_vol
     description: "Advanced - attaching multiple volumes to multiple instances"
requirements: [ "boto" ]
# ...
'''

We can manipulate the machine parsable information (description Vs
code) if we have multiple example we can't split in different example
area,. .., using EXAMPLES this can't be possible and this the example
will be merged in a single example block like:

EXAMPLES = """
# Advanced - attaching multiple volumes to multiple instances

- name: Launch instances
  local_action: ec2 keypair=$keypair image=$image wait=yes count=3
  register: ec2
- name: Create volumes and attach
  local_action: ec2_vol instance=${item.id} volume_size=5
  with_items: ${ec2.instances}
  register: ec2_vol
"""

Le us know the final decision :slight_smile:

6

We are going to stick with the "EXAMPLES" section.

It's just a free form text area so if more than one example needed to
be included, it could be.

It is ideal for including examples of detailed playbooks, among other things.

Both are made accessible by the code in
https://github.com/ansible/ansible/blob/devel/lib/ansible/utils/module_docs.py