# Ansible modules documentation **URL:** \ **Category:** Ansible Project\ **Created:** [March 30, 2013, 1:10pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604 "2013-03-30T13:10:48Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![Marco\_Vito\_Moscarito](https://avatars.discourse-cdn.com/v4/letter/m/97f17d/32.png) [@Marco\_Vito\_Moscarito](https://forum.ansible.com/u/Marco_Vito_Moscarito)\ **Post date:** [March 30, 2013, 1:10pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604/1 "2013-03-30T13:10:48Z")
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](https://github.com/ansible/ansible/pull/2528) ---
**Author:** ![Michael\_DeHaan2](https://avatars.discourse-cdn.com/v4/letter/m/da6949/32.png) [@Michael\_DeHaan2](https://forum.ansible.com/u/Michael_DeHaan2)\ **Post date:** [March 30, 2013, 4:25pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604/2 "2013-03-30T16:25:05Z")
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! ---
**Author:** ![Marco\_Vito\_Moscarito](https://avatars.discourse-cdn.com/v4/letter/m/97f17d/32.png) [@Marco\_Vito\_Moscarito](https://forum.ansible.com/u/Marco_Vito_Moscarito)\ **Post date:** [March 30, 2013, 5:44pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604/3 "2013-03-30T17:44:19Z")
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 = ''' ---
**Author:** ![Michael\_DeHaan2](https://avatars.discourse-cdn.com/v4/letter/m/da6949/32.png) [@Michael\_DeHaan2](https://forum.ansible.com/u/Michael_DeHaan2)\ **Post date:** [March 31, 2013, 2:21pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604/4 "2013-03-31T14:21:32Z")
> 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. ---
**Author:** ![Marco\_Vito\_Moscarito](https://avatars.discourse-cdn.com/v4/letter/m/97f17d/32.png) [@Marco\_Vito\_Moscarito](https://forum.ansible.com/u/Marco_Vito_Moscarito)\ **Post date:** [March 31, 2013, 4:15pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604/5 "2013-03-31T16:15:44Z")
Thanks for reply Michael, I don't discuss your effort on maintains docs in modules and I will adapt what do you (project leader 😃 ) 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 🙂 ---
**Author:** ![Michael\_DeHaan2](https://avatars.discourse-cdn.com/v4/letter/m/da6949/32.png) [@Michael\_DeHaan2](https://forum.ansible.com/u/Michael_DeHaan2)\ **Post date:** [April 1, 2013, 12:56pm UTC](https://forum.ansible.com/t/ansible-modules-documentation/12604/6 "2013-04-01T12:56:39Z")
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](https://github.com/ansible/ansible/blob/devel/lib/ansible/utils/module_docs.py)