ansible-doc-generator

CLI for documenting Ansible roles into Markdown files.

Documentation is generated from magic comments declared in the tasks file of a role, where everycomment should be put before the declaration of the task.

These are the types of comments accepted:

• @metatitle defines a high level title (equivalent to h2). It's expected to be just one metatitle per role
• @title defines the title of the role or the title of the step (it's flexible)
• @comment completes the information provided by the title. This comment allows multiple lines and multiple instances
• @input defines the command or action executed by the task. Produces a block of code. This comment is also multiline
• @output defines the result of the execution. Produces a block of code

Comments allow variable interpolation with the syntax #{var}. If the variable is defined in a sub-level it can be reached using the > operator, i.e. #{apt>pkg}

Here's an example of role that uses most of the comments and variable interpolation:

---
# @metatitle Install Postgresql

# @input wget --quiet -O - #{apt_key>url} | sudo apt-key add -
- name: Add APT key
  become: true
  apt_key:
    url: "https://www.postgresql.org/media/keys/ACCC4CF8.asc"
    state: present

# @title Add repository
# @input sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" >> /etc/apt/sources.list.d/pgdg.list'
- name: Add APT postgres repository
  become: true
  apt_repository:
    repo: deb http://apt.postgresql.org/pub/repos/apt/ {{ansible_distribution_release}}-pgdg main
    state: present
    filename: 'pgdg.list'

# @title Install #{apt>pkg} packages
# @input apt install -y #{apt>pkg | join: ' '}
- name: Install Postgres
  become: true
  apt:
    pkg: ['postgresql-12', 'postgresql-server-dev-12', 'postgresql-contrib-12']
    state: present
    update_cache: yes

# @title Install PostGis 3
# @input apt install -y #{apt>pkg | join: ' '}
- name: Install PostGis
  become: true
  apt:
    pkg: postgresql-12-postgis-3
    state: present

Other features

Localization

@metatitle, @title and @comment support localization, by adding at the end of the label the locale code, i.e.:

# @title_es Instalar Ruby
# @title_en Install Ruby
# @comment_es Este rol instala Ruby utilizando Rbenv.
# @comment_en This role installs Ruby using Rbenv

When calling the generation, you'll need to add a second parameter with the locale you want to generate:

$ ansible-doc-generator ~/ansible/playbooks/ruby.yml es # to generate Spanish documentation

Installation

$ gem install ansible-doc-generator

TODO

• [ ] Provide an example of documented repository
• [ ] better error reporting
• [ ] support includes
• [ ] deal with conditions

For a more complete list review the repository issues.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rspec to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/PopulateTools/ansible-doc-generator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Authors

This is a project developed by Populate team to document our Ansible roles and provide a great documentation to our customers.