Metadata-Version: 2.1
Name: ansible-docgen
Version: 1.0.0
Summary: Generate Documentation from Annotated Ansible Playbooks and Roles
Home-page: https://github.com/starboarder2001/ansible-docgen
Author: David Whiteside
Author-email: david@davidwhiteside.com
License: MIT
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: PyYAML
Requires-Dist: setuptools
Requires-Dist: jinja2

ansible-docgen
=====================

Description
===========

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

[![Build Status](https://app.travis-ci.com/thedavidwhiteside/ansible-docgen.svg?branch=develop "ansible-docs latest build")](http://travis-ci.org/thedavidwhiteside/ansible-docgen)
[![PIP Version](https://img.shields.io/pypi/v/ansible-docgen.svg "ansible-docs PyPI version")](https://pypi.python.org/pypi/ansible-docgen)
[![Coverage Status](https://coveralls.io/repos/thedavidwhiteside/ansible-docgen/badge.svg?branch=develop&service=github)](https://coveralls.io/github/thedavidwhiteside/ansible-docgen?branch=develop)
[![Gitter IM](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/thedavidwhiteside/ansible-docgen)


Installation
===========

```shell
pip install ansible-docgen
```

or

```shell
easy_install ansible-docgen
```

Usage
===========

### Annotate Your Playbooks and Roles
```yaml
---
# test_playbook.yml
# Author: John Doe
# Description: Install a Webserver
- name: Install Apache
  yum: name=httpd state=installed
```
```yaml
---
# 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](test/integration/project1/rolestest/README.md)

`Generated Markup File` [your_ansible_project/roles/README.md](test/integration/project1/roles/README.md)

`Generated Markup File` [your_ansible_project/README.md](test/integration/project1/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](test/integration/project1/otherroles/README.md)

`Generated Markup File` [roles/README.md](test/integration/project1/roles/README.md)

`Generated Markup File` [README.md](test/integration/project1/README.md)

##### Help output
```bash
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](LICENSE.md).

Author
======

David Whiteside (<david@davidwhiteside.com>)
