documentation in my playbooks

Archives Ansible Project
1

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

2

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.

3

Nothing implemented I believe, but see the discussion here:

https://github.com/ansible/proposals/issues/19

Jon

4

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