Show HN: Ansible Doc Generator – Easy documentation for your Ansible roles

CLI for documenting Ansible roles into Markdown recordsdata.

Documentation is generated from magic feedback declared within the responsibilities file of a job, where every statement must aloof be put sooner than the declaration of the duty.

Featured Content Ads

add advertising here

COGNAC Metaverse

Explore World's first metaverse that is as real as our Real world.

https://cognac.knowasiak.com

These are the styles of feedback well-liked:

@metatitle defines a excessive level title (identical to h2). It be anticipated to be supreme one metatitle per role
@title defines the title of the role or the title of the step (it be flexible)
@statement completes the working out supplied by the title. This statement enables a pair of lines and a pair of cases
@enter defines the portray or bolt done by the duty. Produces a block of code. This statement is additionally multiline
@output defines the of the execution. Produces a block of code

That is an example of role that makes use of a bunch of the feedback and variable interpolation (gape clarification below):

http://supreme.postgresql.org/pub/repos/supreme/ `lsb_release -cs`-pgdg critical” >> /and so on/supreme/sources.checklist.d/pgdg.checklist’
– title: Add APT postgres repository
change into: true
apt_repository:
repo: deb http://supreme.postgresql.org/pub/repos/supreme/ {{ansible_distribution_release}}-pgdg critical
remark: veil
filename: ‘pgdg.checklist’

Featured Content Ads

add advertising here

Join Bing with ChatGPT-4

Use the new internet where you get what you ask, Fast and precise using AI.

https://www.bing.com

# @title Set up #{supreme>pkg} packages
# @enter supreme set up -y #{supreme>pkg | join: ‘ ‘}
– title: Set up Postgres
change into: true
supreme:
pkg: [‘postgresql-12’, ‘postgresql-server-dev-12’, ‘postgresql-contrib-12’]
remark: veil
update_cache: yes

# @title Set up PostGis 3
# @enter supreme set up -y #{supreme>pkg | join: ‘ ‘}
– title: Set up PostGis
change into: true
supreme:
pkg: postgresql-12-postgis-3
remark: veil”>

---
# @metatitle Set up Postgresql

# @enter wget --restful -O - #{apt_key>url} | sudo supreme-key add -
- title: Add APT key
  change into: true
  apt_key:
    url: "https://www.postgresql.org/media/keys/ACCC4CF8.asc"
    remark: veil

# @title Add repository
# @enter sudo sh -c 'echo "deb http://supreme.postgresql.org/pub/repos/supreme/ `lsb_release -cs`-pgdg critical" >> /and so on/supreme/sources.checklist.d/pgdg.checklist'
- title: Add APT postgres repository
  change into: true
  apt_repository:
    repo: deb http://supreme.postgresql.org/pub/repos/supreme/ {{ansible_distribution_release}}-pgdg critical
    remark: veil
    filename: 'pgdg.checklist'

# @title Set up #{supreme>pkg} packages
# @enter supreme set up -y #{supreme>pkg | join: ' '}
- title: Set up Postgres
  change into: true
  supreme:
    pkg: ['postgresql-12', 'postgresql-server-dev-12', 'postgresql-contrib-12']
    remark: veil
    update_cache: yes

# @title Set up PostGis 3
# @enter supreme set up -y #{supreme>pkg | join: ' '}
- title: Set up PostGis
  change into: true
  supreme:
    pkg: postgresql-12-postgis-3
    remark: veil

It’s likely you’ll maybe maybe additionally add @title and @statement keywords within the playbook file itself and so they’re going to seem within the starting of the generated documentation as an introduction:

Featured Content Ads

add advertising here

Join Bing with ChatGPT-4

Use the new internet where you get what you ask, Fast and precise using AI.

https://www.bing.com

---
# @title Installation files for the app ambiance
# @statement We will ingredient easy the high-quality technique to set up the ambiance and the app
# in a server from the scratch.
# @statement Very first thing you want to to set up is Python and Ansible.
- hosts: all
  roles:
    - { role: 'handlers' }
    ...

Diversified aspects

Localization

@metatitle, @title and @statement toughen localization, by adding on the tip of the keep the locale code, i.e.:

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

To rep the Spanish documentation it is advisable to aloof whisk:

$ ansible-doc-generator -p ~/ansible/playbooks/ruby.yml -l es

Variable interpolation

Feedback enable variable interpolation with the syntax #{var}. If the variable is defined in a sub-level it would also additionally be reached using the > operator, i.e. #{supreme>pkg}.

Example:

Inline syntax is additionally supported:

File interpolation

It’s likely you’ll maybe maybe print the output of a file positioned internal recordsdata or template of the identical role with the syntax f{filename.txt}.

As an instance, given the next job internal the role nginx/responsibilities/critical.yml, this may maybe maybe well glance the file in nginx/recordsdata/nginx.monit and nginx/templates/nginx.monit and put its direct material.

# @enter f{nginx.monit}
- title: Copy the nginx monit carrier recordsdata
  reproduction:
    src:

Knowasiak