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 6d9f94a1ce
Add sponsors setup
2 weeks ago
.github Add sponsors setup 2 weeks ago
ansible_readme Change back reference naming and add it to more places 1 month ago
changelog Bootstrap an initial stab at ansible-readme 1 month ago
documentation Add discussions links 1 month ago
test Bootstrap an initial stab at ansible-readme 1 month ago
.gitignore Ignore other roles for easy testing 1 month ago
.readthedocs.yml Bootstrap an initial stab at ansible-readme 1 month ago
.travis.yml Bootstrap an initial stab at ansible-readme 1 month ago
CHANGELOG.rst Add changelog entries for latest fixes 1 month ago
CONTRIBUTING.rst Bootstrap an initial stab at ansible-readme 1 month ago
LICENSE Bootstrap an initial stab at ansible-readme 1 month ago
MANIFEST.in Include templates as package data 1 month ago
README.rst Add sponsors setup 2 weeks ago
mypy.ini Bootstrap an initial stab at ansible-readme 1 month ago
pyproject.toml Fix towncrier integration 1 month ago
setup.cfg Add classifiers and keywords 1 month ago
setup.py Bootstrap an initial stab at ansible-readme 1 month ago
tox.ini Bootstrap an initial stab at ansible-readme 1 month ago

README.rst

ansible-readme

Travis CI result Documentation status Support badge

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.