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.
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.
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
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.
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.
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