documentation in my playbooks

[eric.b....@nasa.gov]

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

[Jonathan Lozada De La Matta]

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.

--
You received this message because you are subscribed to the Google Groups "Ansible Project" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ansible-proje...@googlegroups.com.
To post to this group, send email to ansible...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/ansible-project/28412c42-bbd7-4d2b-8c67-db3b5b652f7c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Jonathan lozada de la matta

AUTOMATION CONSULTANT - AUTOMATION PRACTICE

Red Hat Consulting Services

jloz...@redhat.com   

 

[J Hawkesworth]

Nothing implemented I believe, but see the discussion here:

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

Jon

[Jonathan Lozada De La Matta]

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

--

You received this message because you are subscribed to the Google Groups "Ansible Project" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ansible-proje...@googlegroups.com.
To post to this group, send email to ansible...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/ansible-project/6d47bd89-25df-4d62-8998-ff55474206be%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.