Skip to main content

Ansible role automatic documentation

Project description

Ansible Never Write the Doc

Build Status License: MIT PyPI version Upload Pypi & build docker

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 :

pip install ansible-nwd

Now you can use it on your ansible role !

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

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

or

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 :

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:

your_variable: your_value # description of your variable;type

For example :

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:

# @var variable;description;type;example;mandatory(bool)

For example :

# @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 :

For example :

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:

# 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansible-nwd-0.6.tar.gz (7.4 kB view hashes)

Uploaded Source

Built Distribution

ansible_nwd-0.6-py3-none-any.whl (8.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page