Reading the Ansible documentation in vim
Ansible has a great documentation and docs.ansible.com is probably the website we visit most often when we write Ansible playbooks or roles. However using a mouse and scroll through text in a browser window is probably not the most efficient way to do that. There is a better way.
A couple of years ago I had a colleague who had a strong belief that automation was a bad thing and he tried to prove it at every opportunity. Even though we had introduced Ansible and explained to him how to use it he still continued to make undocumented ad hoc changes to production servers.
What happened? Of course Ansible did its job and reverted his changes. For him that seemed to be another proof that Infrastructure as Code did not work at all. His excuse for not doing it right was that Ansible was way to complicated and he couldn’t find any documentation on it. That is probably the lamest excuse I ever heard for not to use Infrastructure as Code.
We all know docs.ansbile.com that most of us use on a daily basis. But reading text in a browser comes with a lot of overhead that makes it very inefficient if we do it dozens of times a day. So here is a way to make reading Ansible documentation more efficient. Besides docs.ansible.com there is the ansible-docs command that literally has the same information on modules.
The ansible-doc has documentation on all sorts of plugins. We can print out a full list with ansible-doc -l. If we want to narrow it down to just modules we can use the -t option ansible-doc -lt module
Let’s say we want to allocate an elastic IP on AWS
ansible-doc -lt module | grep "ansible-doc -lt module | grep "elastic IP"
We will find the community.aws.ec2_eip module and can read the module documentation with
ansible-doc community.aws.ec2_eip
So far this it not really faster than just google it and read it in a browser. But now comes the cool part that makes this superior to using a browser.
We can pipe that into vim to make reading more comfortable.
ansible-doc community.aws.ec2_eip | vim -
Once we have the documentation open in vim we can do all sorts of things like deleting stuff or adding our own annotations. We can save the file somewhere and use it as a blueprint for our own documentation.
I prefer to get away with new lines to make it more compact as indent based folding already provides a good visual guideline.
ansible-doc community.aws.ec2_eip | sed '/^$/d' | vim -
In addition to just reading and modifiying the documentation ansible-doc allows us to create a snippet that we can add into our playbook.
ansible-doc -s community.aws.ec2_eip >> playbook.yml
Well, certainly there are reasons not to use Ansible in some scenarios but poor documentation is definitely not on that list.
