# documentation in my playbooks

**URL:** <https://forum.ansible.com/t/documentation-in-my-playbooks/28319>\
**Category:** Ansible Project\
**Created:** [August 13, 2018, 12:04pm UTC](https://forum.ansible.com/t/documentation-in-my-playbooks/28319 "2018-08-13T12:04:17Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![erichymowitz](https://avatars.discourse-cdn.com/v4/letter/e/9d8465/32.png) [@erichymowitz](https://forum.ansible.com/u/erichymowitz)\
**Post date:** [August 13, 2018, 12:04pm UTC](https://forum.ansible.com/t/documentation-in-my-playbooks/28319/1 "2018-08-13T12:04:17Z")

</div>

Short question:

Is it possible for me to leverage whatever-it-is that makes ansible-doc work for my own playbooks?

Long drawn-out question:

So I’m fairly new to ansible. I’m much more used to writing shell scripts and/or perl scripts. Both bash and perl have a way to create a -h and/or --help flag that will generate documentation instead of actually running the script. Perl goes even further with “pod” which has a program to display man-page-esque information.

Does ansible-playbook have anything similar? The closest I’ve been able to figure out is something like this:

`  
tasks:

- name: Help message  
block:
- pause:  
prompt: |-  
This is a Literal Block Scalar.  
It will display the text  
exactly  
as it appears here with newlines  
and extra spaces. I can use an optional minus sign to  
prevent a final newline.

Hit Return to continue

- fail:  
msg: “Aborting after requesting help”  
when: help is defined
- debug:  
msg: “\n\nHi There from {{inventory\_hostname}}\n\n”

`

This works … but it’s a little clunky. I have to remember to call it

ansible-playbook -e help=1 playbook.yaml

But I would **love** to be able to run

ansible-doc playbook.yaml

and have it either generate documentation (that I would, of course, write) or generate an error that no documentation is available.

Is this possible?

–EbH

---

<div class="post-metadata">

**Author:** ![Jonathan\_Lozada\_De\_L](https://avatars.discourse-cdn.com/v4/letter/j/eb8c5e/32.png) [@Jonathan\_Lozada\_De\_L](https://forum.ansible.com/u/Jonathan_Lozada_De_L)\
**Post date:** [August 13, 2018, 12:31pm UTC](https://forum.ansible.com/t/documentation-in-my-playbooks/28319/2 "2018-08-13T12:31:22Z")

</div>

Eric,

The best way to write documentation on the tasks is by describing it in - name: “here is everything i’m doing in this tasks and I can include “{{ variables }}” if I want”. I suggest the description you have in the prompt to put it in the - name. Then every task you do will have a -name and just be describe there whatever you are doing. If you want you can point to the module documentation in - name or do like other scripts and use a lot of ##### and put more information. I wouldn’t recommend what you are trying to do.

---

<div class="post-metadata">

**Author:** ![j.r.hawkesworth](https://avatars.discourse-cdn.com/v4/letter/j/a3d4f5/32.png) [@j.r.hawkesworth](https://forum.ansible.com/u/j.r.hawkesworth)\
**Post date:** [August 13, 2018, 3:09pm UTC](https://forum.ansible.com/t/documentation-in-my-playbooks/28319/3 "2018-08-13T15:09:03Z")

</div>

Nothing implemented I believe, but see the discussion here:

[https://github.com/ansible/proposals/issues/19](https://github.com/ansible/proposals/issues/19)

Jon

---

<div class="post-metadata">

**Author:** ![Jonathan\_Lozada\_De\_L](https://avatars.discourse-cdn.com/v4/letter/j/eb8c5e/32.png) [@Jonathan\_Lozada\_De\_L](https://forum.ansible.com/u/Jonathan_Lozada_De_L)\
**Post date:** [August 13, 2018, 3:56pm UTC](https://forum.ansible.com/t/documentation-in-my-playbooks/28319/4 "2018-08-13T15:56:27Z")

</div>

I agree with the responses in there. Besides in the tasks, there’s a readme file and other ways to have this information.