Generate documenting README files for Ansible roles https://github.com/pycontribs/ansible-readme
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Luke Murphy 480b5669fe
Add discussions links
1 week ago
ansible_readme Change back reference naming and add it to more places 1 week ago
changelog Bootstrap an initial stab at ansible-readme 1 week ago
documentation Add discussions links 1 week ago
test Bootstrap an initial stab at ansible-readme 1 week ago
.gitignore Ignore other roles for easy testing 1 week ago
.readthedocs.yml Bootstrap an initial stab at ansible-readme 1 week ago
.travis.yml Bootstrap an initial stab at ansible-readme 1 week ago
CHANGELOG.rst Add changelog entries for latest fixes 1 week ago
CONTRIBUTING.rst Bootstrap an initial stab at ansible-readme 1 week ago
LICENSE Bootstrap an initial stab at ansible-readme 1 week ago
MANIFEST.in Include templates as package data 1 week ago
README.rst Add note about IRC channel 1 week ago
mypy.ini Bootstrap an initial stab at ansible-readme 1 week ago
pyproject.toml Fix towncrier integration 1 week ago
setup.cfg Add classifiers and keywords 1 week ago
setup.py Bootstrap an initial stab at ansible-readme 1 week ago
tox.ini Bootstrap an initial stab at ansible-readme 1 week ago

README.rst

ansible-readme

Travis CI result Documentation status

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.