ansible-docgen

Description

ansible-docgen generates documentation from annotated Ansible Playbooks and Roles.

Installation

pip install ansible-docgen

or

easy_install ansible-docgen

Usage

Annotate Your Playbooks and Roles

---
# test_playbook.yml
# Author: John Doe
# Description: Install a Webserver
- name: Install Apache
  yum: name=httpd state=installed

---
# roles/appserver/tasks/main.yml
# Author: John Doe
# Description: Appserver role
- name: Copy Installer
  copy: src=installer dest=/tmp/
  tags:
    - copy-installer
- name:  Run Installer
  shell: /tmp/installer.sh
  tags:
    - run-installer

Generate Documentation from Annotation

Use -p to specify your project directory. Click the links to preview the Markup generated by ansible-docgen. Warning: This will overwrite existing README files.

ansible-docgen -p your_ansible_project

Generated Markup File your_ansible_project/rolestest/README.md

Generated Markup File your_ansible_project/roles/README.md

Generated Markup File your_ansible_project/README.md

If your current directory is your project directory just run ansible-docgen without any arguments. Warning: This will overwrite existing README files.

cd your_ansible_project && ansible-docgen

Generated Markup File otherroles/README.md

Generated Markup File roles/README.md

Generated Markup File README.md

Help output

usage: ansible-docgen [-h] [-p PROJECT] [-f FILENAME] [-s STYLE] [-n] [-v]

options:
  -h, --help            show this help message and exit
  -p PROJECT, --project PROJECT
                        Path to Ansible project. Default is the current directory.
  -f FILENAME, --filename FILENAME
                        filename used for the output documentation file. Default is README
  -s STYLE, --style STYLE
                        Choose the format for the documentation. Default is markdown. Example: --style=[markdown]
  -n, --no-tags         This option disables show tags in the documentation
  -v, --version         Print version

License

ansible-docgen is released under the MIT License.

Author

David Whiteside ([email protected])