"As I ansible user I would like to use docstrings in yaml file and quickly build documentation (the best for sphinx-doc if possible). Something like doxygen is doing for C++ code."
You could look at a new project ansible-docgen <https://github.com/starboarder2001/ansible-docgen>. On Monday, February 17, 2014 at 1:45:49 PM UTC-7, Marcin Prączko wrote: > > Dear ansible users, > > I am using ansible and must admit that I am quite happy with it. > Challanges which I started to have are: > > 1. Documentation from yaml files (roles / playbook / etc). > 2. Visibility what ansible will do. > > A bit more about this: > # 1. > I started using sphinx-doc for documentation for some projects and must > admit that is working very well and as expected. I know that ansible is > written in python which support docstrings in code and sphinx-doc can read > python modules and generate documentation (this is how ansible-doc is > generated). However so far I didn't find any way of generate documentation > from yaml file. My google skills didn't help me a lot in this area. > > As I ansible user I would like to use docstrings in yaml file and quickly > build documentation (the best for sphinx-doc if possible). Something like > doxygen is doing for C++ code. > > Do you know any already existed solutions or do I have to write my own > parser / generator? > How do you documenting your playbook to quickly see what is happening? > > I know that ansible has been designed to be easy to read and understand - > and ansible developers meet this goal. However when code is growing up and > more and more roles exists, is (for me) harder and harder remember how role > has been designed and why this way :) > > #2. > Visibility - I am not speaking about --check --diff options. They do what > must be done - and works well. More I am speaking about following scenario: > T = Time (day / week / etc). > T1 = Some initial ansible code has been created and deployed on new VM > (Works :)) > T2 = Changes in ansible code to allow run some specific tasks at hock. > T3 = Adjust ansible to run some tasks on already configured hosts > T4 = New machine is setup - how to know what ansible will do exectly ??? > > I know that ansible has option --list tasks, --list-hosts, etc - but > during development code changes quickly and '--list-tasks' can show me > clearly which tasks will run, but doesn't show logic of operation (Which > variables must be setup for playbook, how it will work, what is really > installing) - for example for tasks with lists - no clear info what will be > installed, etc. > > IMHO, this is related with #1 (documentation). > > How do you sort this challange - how do you know what ansible will do and > whether nothing will be broken on already existing environments? > Real example: > - I had to setup mysql server on 10 hosts (lucky for me not in production > yet). (CentOS) > - During development of ansible palybook we added uninstalling some old > version of package (in thory not related with mysql) > - Ansible work as expected - all taks has been done, but wait - from some > reason uninstalling package - uninstalled mysql-server because of > depenecies (yeap yum issue :() > - Lucky for me I didn't lost data - only binaries. So next quick task in > ansible and install mysql-server sorted this quickly. > > But this is what I am talking in terms of risk and visibility - what > ansible will do. > > Appologise for long email, hope that you have some experience, hints how > to deal with these challanges. > > Best regards, > Marcin Praczko > -- 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 [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/ansible-project/0f9a569b-43a7-4e53-8700-448d40c82fa7%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
