# Module self documentation thoughts.

**URL:** <https://forum.ansible.com/t/module-self-documentation-thoughts/11401>\
**Category:** Ansible Project\
**Created:** [April 8, 2012, 1:19am UTC](https://forum.ansible.com/t/module-self-documentation-thoughts/11401 "2012-04-08T01:19:23Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![Brad\_Olson](https://avatars.discourse-cdn.com/v4/letter/b/779978/32.png) [@Brad\_Olson](https://forum.ansible.com/u/Brad_Olson)\
**Post date:** [April 8, 2012, 1:19am UTC](https://forum.ansible.com/t/module-self-documentation-thoughts/11401/1 "2012-04-08T01:19:23Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Michael\_DeHaan](https://avatars.discourse-cdn.com/v4/letter/m/c4cdca/32.png) [@Michael\_DeHaan](https://forum.ansible.com/u/Michael_DeHaan)\
**Post date:** [April 8, 2012, 12:48pm UTC](https://forum.ansible.com/t/module-self-documentation-thoughts/11401/2 "2012-04-08T12:48:44Z")

</div>

This is mostly already covered by the web documentation: [http://ansible.github.com/modules.html](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](https://github.com/ansible/ansible.github.com/tree/master/rst)

–Michael

---

<div class="post-metadata">

**Author:** ![Brad\_Olson](https://avatars.discourse-cdn.com/v4/letter/b/779978/32.png) [@Brad\_Olson](https://forum.ansible.com/u/Brad_Olson)\
**Post date:** [April 9, 2012, 4:40pm UTC](https://forum.ansible.com/t/module-self-documentation-thoughts/11401/3 "2012-04-09T16:40:59Z")

</div>

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](https://github.com/ansible/ansible.github.com/tree/master/rst)

--Brad

---

<div class="post-metadata">

**Author:** ![Michael\_DeHaan](https://avatars.discourse-cdn.com/v4/letter/m/c4cdca/32.png) [@Michael\_DeHaan](https://forum.ansible.com/u/Michael_DeHaan)\
**Post date:** [April 9, 2012, 4:45pm UTC](https://forum.ansible.com/t/module-self-documentation-thoughts/11401/4 "2012-04-09T16:45:23Z")

</div>

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.