2026-02-02, 17:15–17:40, B.1.0.14
Maintaining accurate, up-to-date documentation for Ansible roles is a persistent challenge when maintaining ansible roles. ansible-docsmith solves this problem by automating documentation generation from a single source of truth - argument_specs.yml file.
In this talk, we'll explore ansible-docsmith and how to use it to forget about ever updating the readme.md file for the role, but always keeping it up to date.
- Using argument_specs.yml as the single source of truth for ansible role readme.md file
- Using ansible-docsmith in CI/CD: automation pipelines and pre-commit hooks, making documentation updates effortless
- Available customization options in ansible-docsmith: how to use Jinja2 templates to generate readme.md according to your specific documentation standards
- Compare ansible-docsmith with ansibull-docs - pros and cons, use case scenarios
Attendees will gain hands-on familiarity with:
- Installing and configuring ansible-docsmith in their environment
- Setting up documentation markers in README files
- Using ansible-docsmith generate and validate commands effectively
- Integrating the tool into CI/CD pipelines and Git hooks
- Creating custom Jinja2 templates for specialized documentation needs
- Best practices for maintaining argument_specs.yml as documentation source
Whether you maintain a handful of roles or manage entire collections, you'll learn how to save time, reduce errors, and keep your role documentation perfectly synchronized with your code.
Target Audience: Ansible users, DevOps engineers, infrastructure automation practitioners
Kirill Satarin works as principal software engineer at Red Hat with focus on SAP automation with Ansible.