ansdoc

Description

ansdoc is a dead-simple CLI tool written in Go, that scans your Ansible Role Vars file (usually defaults/main.yml, change by using --file | -f flag) and generates a Markdown Table accordingly.

The variable description is taken be the leading headcomment of each variable (see Example).

ansdoc allows you to insert the generated Markdown Table in a specified output-file (use --output-file | -o) that needs to have two <!--ansdoc --> separators (see README.md.

Features

• support multiline comments
• configurable via env vars (ANSDOC_FILE, ANSDOC_OUTPUT_FILE, ANSDOC_INSERT, ANSDOC_BACKUP)
• insert table in a specified output file
• keep backup of output-file when inserting content

Integrations

• ansdoc-action
• pre-commit-hook

Usage

> ansdoc -h
out-of-the-box documentation for any Ansible Role

Usage:
  ansdoc [flags]
  ansdoc [command]

Flags:
  -b, --backup               backup the output file before writing
  -f, --file string          path to the variables file (default "defaults/main.yml")
  -i, --insert               insert mode, inserts the markdown table in the specified output file (default true)
  -o, --output-file string   where to write the output to (requires insert mode) (default "README.md")

Example

defaults/main.yml

# this enables the deployment
enable: true

# specify your toplevel domain
domain: ansible.com

# number of clients
number_of_clients: 42 

# valid user IDs
user_ids: [1, 2, 3]

# supported OS
os:
  linux: true
  mac: false
  windows: false

#we also support jinja & you dont even need a leading space :)
jinja: |
  [
  {% for server in groups[vault_raft_group_name] %}
    {
      "peer": "{{ server }}",
      "api_addr": "{{ hostvars[server]['vault_api_addr'] |
      default(vault_protocol + '://' + hostvars[server]['ansible_' + hostvars[server]['ansible_default_ipv4']['interface']]['ipv4']['address'] + ':' + (vault_port|string)) }}"
    },
  {% endfor %}
  ]

by running:

> ansdoc

ansdoc creates:

Name	Description	Default Value
enable	enable the deployment	true
domain	specify your toplevel domain	ansible.com
number_of_clients	number of clients	42
user_ids	valid user IDs	[1 2 3]
os	supported OS	linux: true mac: false windows: false
jinja	we also support jinja & you dont even need a leading space :)	[ {% for server in groups[vault_raft_group_name] %} { "peer": "{{ server }}", "api_addr": "{{ hostvars[server]['vault_api_addr'] | default(vault_protocol + '://' + hostvars[server]['ansible_' + hostvars[server]['ansible_default_ipv4']['interface']]['ipv4']['address'] + ':' + (vault_port|string)) }}" }, {% endfor %} ]

Installation

# curl
version=$(curl -S "https://api.github.com/repos/FalcoSuessgott/ansdoc/releases/latest" | jq -r '.tag_name[1:]')
curl -OL "https://github.com/FalcoSuessgott/ansdoc/releases/latest/download/ansdoc_${version}_$(uname)_$(uname -m).tar.gz"
tar xzf "ansdoc_${version}_$(uname)_$(uname -m).tar.gz"
./ansdoc version

# Go 
go install github.com/FalcoSuessgott/ansdoc@latest
ansdoc version

# Docker/Podman
docker run ghcr.io/falcosuessgott/ansdoc version

# Ubuntu/Debian
version=$(curl -S "https://api.github.com/repos/FalcoSuessgott/ansdoc/releases/latest" | jq -r '.tag_name[1:]')
curl -OL "https://github.com/FalcoSuessgott/ansdoc/releases/latest/download/ansdoc_${version}_linux_amd64.deb"
sudo dpkg -i "./ansdoc_${version}_linux_amd64.deb"
ansdoc

# Fedora/CentOS/RHEL
version=$(curl -S "https://api.github.com/repos/FalcoSuessgott/ansdoc/releases/latest" | jq -r '.tag_name[1:]')
curl -OL "https://github.com/FalcoSuessgott/ansdoc/releases/latest/download/ansdoc_${version}_linux_amd64.rpm"
sudo dnf localinstall "./ansdoc_${version}_linux_amd64.rpm"
ansdoc

# Sources
git clone https://github.com/FalcoSuessgott/ansdoc && cd ansdoc
go build 

pre-commit-hook

repos:
  - repo: https://github.com/FalcoSuessgott/ansdoc
    rev: master
    hooks:
      - id: ansdoc-go # if ansdoc installed via go
        args: ["-i", "-f", "defaults/main.yml", "-o", "README.md"]

      - id: ansdoc-system # if ansdoc installed via your system manager (e.g .deb, .rpm)
        args: ["-i", "-f", "defaults/main.yml", "-o", "README.md"]

      - id: ansdoc-docker # if ansdoc installed via docker/podman
        args: ["-i", "-f", "defaults/main.yml", "-o", "README.md"]