PROPOSAL: 'description' parameter

[shirou]

Hi list,

I'd like to open a discussion about "description" parameter.
Ansible does nothing about on it. It just describing what is it.

I know YAML can have a comment and name is good to know what this task
do. But comment is not structured and name can not be long because
handlers use it.

If ansible defines "description", some documentation tool like Sphinx
[1] can read it and produces a good document.


---
- hosts: all
description: This playbook is an example for describe parameter
tasks:
- name: create empty file
file: path=/tmp/empty state=touch
description: >
This empty file is needed to later tasks,
such as A, B, and C. so we have to do blah blah blah
- name: do some script
script: /some/local/script.sh
description:
- a
- b
- c
- script: /some/local/script.sh
description:
can: use map
some: thing
other: thing

- include: other.yml
description:
- include can have description also

I have made PR which make very small change.
https://github.com/ansible/ansible/pull/9230


Thanks for your feedback.

[1] Sphinx: http://sphinx-doc.org/


WAKAYAMA Shirou

[Michael DeHaan]

Typically "name" has been used to provide a user readable comment and we haven't added code for ecosystem things that aren't part of the ansible project.

One thing of caution to mention is that, currently, on the include this would set a variable called "description".

My gut feeling is some playbook "output" tool would have to exist to want to do that first.

--
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/CANCK7Kf%3Dciuy8FNnfFqb8DapmdfqFH8UWUqeMFA6VAwbBjoZTQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[shirou]

Thank you for the comment.


'name' is always printed when you play. If name is long, the output
becomes too verbose.
I mentioned the Sphinx in the previous mail, but we can implements an
ansible command which can output description.

When many people write playbooks for a long time, it is easy to lost
the purpose and/or the reason of tasks/includes.
I think some documentation tool which can integrated to the playbook
is needed for the long-term DevOps.

> One thing of caution to mention is that, currently, on the include this would set a variable called "description".

I want to add description not only a playbook but also tasks or
includes which can not define variables.

> My gut feeling is some playbook "output" tool would have to exist to want to do that first.

It could be. But it will bring complexity.


Regards,
WAKAYAMA Shirou

> https://groups.google.com/d/msgid/ansible-project/CA%2BnsWgz-_ypp5N1Gvr4tfP%2B2t5wCrbheMSekX3qQx5HrcaRmXw%40mail.gmail.com.

[Mark]

Why would the use of the '#' be not desirable? Ofcourse if you want to print the comments this won't work but I can hardly imagine you want all that output on your screen.

Op woensdag 1 oktober 2014 15:38:18 UTC+2 schreef Shirou w:

[Michael DeHaan]

Right, I think I'm leaning on "#" for YAML comments.

The only disadvantage is if you had something "reading" the YAML to generate it, that would be harder, but it would have to understand playbook includes and task includes and role dependencies, to get it right.

That might be difficult.

We've just begun a bit of a refactoring effort to make much of this easier - to where a generator could easily step through tasks and walk them, but .. yeah, the idea of a documentation tool for documenting playbooks seems to be a little strange to me, as I feel playbooks are that documentation.

Having a structured "description" really doesn't hurt much though, it's innocuous.  

To view this discussion on the web visit https://groups.google.com/d/msgid/ansible-project/3e5bb4c4-8968-40b2-9cc0-f61b1b8fc45c%40googlegroups.com.

[shirou]

Thank you for your feedbacks.

I agree playbooks are the documentation and YAML comments are enough for
just reading some playbooks.

I think playbooks are "source codes" and tasks are "functions". My
description proposal is looks like "annotation" for a "function" or a
"class". Annotations are formatted and used with comments all together.

Please imagine there are hundreds of playbooks which someone wrote 3
years ago. Formatted description and a documentation tool can help you
to understand at a glance what the playbook and the task is.

A discussion of the structure under the description is still needed
for good documentation, but 'description' parameter or something like
that is a good start point, I think.


Regards,
WAKAYAMA Shirou