Generate documenting README files for Ansible roles¶
The time is still ripe (tonk, June 2016 (!)) for standardised role documentation but in the absence of this the Ansible community must step up and try to formalise what is already being done and what should be done to document roles.
Ansible-Readme is a tool which aims to enable the Ansible community to try and come to a consensus on how we would like the standardisation of role documentation to look like and what tools we need to do that. It does not intend to be the last word but instead proposes an approach based on the needs of the author. New approaches are welcome (let us implement them or at least document them). In short, this is an experiment and your participation is required.
The core principle is this: we need to generate the documentation based on the role directory structure. This arises out of applying the “Do One Thing and Do It Well” philosophy to developing roles. And as we have seen in practice, the maintenance burden increases dramatically with this approach as the number of roles increases. Whatever hand written documentation there is can quickly get out of sync or sometimes be abandoned altogether.
Please join the discussion on the issue tracker or on IRC at
#ansible-readme on Freenode.
Ansible-Readme in current form is meant primarily as an unstable proof-of-concept tool. The project does follow Semantic versioning conventions but there are no guarantees that certain approaches will continue to be supported on major releases. Therefore it is advised to not invest in using the tool to document your roles just yet until it is clear what approaches are worth following.