Metadata-Version: 2.1
Name: ansible-nwd
Version: 0.4
Summary: Ansible role automatic documentation
Home-page: https://github.com/VasseurLaurent/ansible-nwd
Author: VASSEUR Laurent
Author-email: mail.laurentvasseur@gmail.com
License: MIT License
Download-URL: https://github.com/VasseurLaurent/ansible-nwd/archive/v0.4.tar.gz
Keywords: ansible,documentation,automation
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: ruamel.yaml
Requires-Dist: ruamel.yaml.clib
Requires-Dist: jinja2-time

# Ansible Never Write the Doc

[![Build Status](https://travis-ci.com/VasseurLaurent/ansible-nwd.svg?branch=master)](https://travis-ci.com/VasseurLaurent/ansible-nwd) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyPI version](https://badge.fury.io/py/ansible-nwd.svg)](https://badge.fury.io/py/ansible-nwd) ![Upload Python Package](https://github.com/VasseurLaurent/ansible-nwd/workflows/Upload%20Python%20Package/badge.svg)

## Introduction

``Ansible Never Write the Doc`` provides you an automatic way to create Ansible roles documentation.

It parses all Ansible roles folders and gathers information to write them into a ``Readme.md`` for you.

``Ansible-nwd`` is also compatible with ``molecule`` , it will parse your different scenarios and write them into your documentation file.

## Get started with pip !

`Ansible-nwd` is really easy to use.

First of install it with pip :

```shell
pip install ansible-nwd
```

Now you can use it on your ansible role !

FIll in your ansible role to follown ```Ansible-nwd``` pattern and :

```shell
ansible-nwd -m 'path/to/your/role'
```

or

```shell
cd 'path/to/your/role' && ansible-nwd
```

That's it ! Your documentation is ready

## Get started with docker !

You can simply run the docker in your Ansible role folder such as :

```shell
docker run -v $(pwd):/data laurentvasseur/ansible-nwd
```

That's it ! Your documentation is ready

## How does it work ?

``Ansible-nwd`` will parse your Ansible roles folders and , according to the folder and some patterns found in your yaml files it will gather information for you.

Currently, it parses these following folders:

* default

* meta

* molecule

* tasks

Check below to know which pattern are recognized.

### Default

In the folder ``default`` you can have two different patterns:

* Default variables defined
* Variables not defined by default but useful for your role

#### Default variables defined

If you define a default variable, they will be retrieved by ``Ansible-nwd`` and their default values will be written in the documentation file.

Moreover, you can add information about these variables following this pattern:

```yaml
your_variable: your_value # description of your variable:type
```

For example :

```yaml
default_variable1: 1.8 # default variable1 version:number
default_variable2: 2.7 # default variable2 version:number
other_variable: 3.4 # other variable version:number
test: 4.5
```

Will create this entry in your documentation file :


Variable | Value | Description | Type
--- | --- | --- | --- |
``default_variable1`` | 1.8 | default variable1 version | number |
``default_variable2`` | 2.7 | default variable2 version | number |
``other_variable`` | 3.4 | other variable version | number |
``test`` | 4.5 | n/a | n/a |

### Variables not defined by default

There are some variables that you cannot define by default or not mandatory for your role.

With  ```Ansible-nwd ``` you can define some variables thank to tags in comment.

For example, if you want to specify a variable which is not defined as default you can do it following this pattern:

```yaml
# @var variable:description:type:example:mandatory(bool)
```

For example :

```yaml
# @var variable:variable description:type:example:false
# @var variable2:description2:type2:example2:true
```

Will create this entry in your documentation file :

Variable | Type | Mandatory |  Example | Description
--- | --- | --- | --- | --- |
`variable`  | type | false | example | variable description |
`variable2`  | type2 | true | example2 | description2 |

### Meta

In the meta folder, ``Ansible-nwd`` will gather these following information:

* Author
* Description
* Minimum Ansible Version
* Platforms

### Molecule

In the folder molecule, ``Ansible-nwd`` will parse each subfolders (we consider one driver per folder ) and will gather information about available test plaforms written in the file ```molecule.yml``` .

For now only 3 drivers are gathered by ```Ansible-nwd``` :

* docker
* vagrant : https://pypi.org/project/molecule-vagrant/
* ec2 : https://pypi.org/project/molecule-ec2/

For example :

```yaml
driver:
  name: docker

platforms:
  - name: debian10
    image: geerlingguy/docker-debian10-ansible
    pre_build_image: true
  - name: debian9
    image: geerlingguy/docker-debian9-ansible
    pre_build_image: true
```

Will create the following entry in the documentation :

Scenario | Platform name | Image |
--- | --- | --- | 
``docker`` | debian10 | geerlingguy/docker-debian10-ansible | 
``docker`` | debian9 | geerlingguy/docker-debian9-ansible |

### Tasks

A common workflow when developing an Ansible roles is to add only ```include``` command in the file ```tasks/main.yml```. It can be really useful to add tags to these include to allow shorter deployment.

```Ansible-nwd``` will read these tags and write them in the documentation.

For example: 

```yaml
# tasks file for python3

  - include: packages.yml
    tags:
      - python3_packages
      - python3

  - include: boto.yml
    tags:
      - python3_boto
      - python3
```

Will create the following entry in the documentation:

These tasks tags are available :

* ``python3``

* ``python3_boto``

* ``python3_packages``


