Metadata-Version: 2.1
Name: ansible-nwd
Version: 0.2
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.2.tar.gz
Description: # 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)
        
        ## Introduction
        
        ``Ansible Never Write the Doc`` provides you an automatic way to create Ansible roles.
        
        It parses all Ansible roles folder and get gathers information to write them in a ``Readme.md`` for you.
        
        ``Ansible-nwd`` is also compatible with ``molecule`` , it will parse your different scenario and write them into your documentation file.
        
        ## Get started !
        
        `Ansible-nwd` is really easy to use.
        
        First clone the repository :
        
        ```shell
        git clone https://github.com/VasseurLaurent/ansible-nwd.git
        ```
        
        Then install python requirements:
        
        ```shell
        pip install -r requirements.txt
        ```
        
        Now you can use it on your ansible role !
        
        FIll in your ansible role to follown ```Ansible-nwd``` pattern and :
        
        ```shell
        python main.py -m 'path/to/your/role'
        ```
        
        That's it ! Your documentation is ready
        
        ## How does it work ?
        
        ``Ansible-nwd`` will parse your folders Ansible roles and according to the folder and some patterns found in your yaml files it will gathers 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 pattern:
        
        * Default variables defined
        * Variables not defined by default but useful for your role
        
        #### Default variables defined
        
        If you define default variable, they will be retrieve by ``Ansible-nwd`` and their default value 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 the following 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 subfolder (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``
        
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
