u/MacLotsen

I’ve been experimenting with a literate-programming approach for Ansible: keeping the operational explanation next to the tasks, while generating a readable Operator’s Handbook from the same YAML file.

The convention is deliberately simple:

• lines starting with ## become prose in the handbook;
• ordinary # comments remain part of the source listing;
• everything else remains normal Ansible YAML.

Because ## is still an ordinary YAML comment, the annotated role does not need to be preprocessed before Ansible can use it.

No generated playbook. No separate “documentation version”. No extra file that can drift away from the automation.

The example in the images is taken from a real role in our infrastructure repository. It provisions a TeX Live package mirror on AlmaLinux and covers, among other things:

• SELinux labelling for content under /srv;
• a systemd service and timer;
• nginx;
• firewalld;
• the mirror synchronisation process.

You do not need to know anything about TeX or LaTeX for the mechanism itself. The relevant point is that the same role file serves two purposes:

1. Ansible loads the YAML as-is.
2. comment2tex turns the extended comments into typeset operational documentation.

The images show the same 33 source lines twice: first as the annotated YAML, then as the generated handbook page.

I also checked the annotated source with both a YAML parser and ansible-playbook --syntax-check; no stripped or generated copy was required.

I can see this being useful for:

• documenting why a task exists, not merely what it does;
• recording operational constraints next to the implementation;
• onboarding new administrators;
• keeping runbooks and automation from diverging;
• retaining a directly usable source file when an urgent change is needed.

The tool is called comment2tex. Version 1.1 adds YAML and Makefile support alongside Bash and Lua.

I’d be interested to hear how other Ansible users handle this. Do you keep detailed operational reasoning inside roles, in separate documentation, or somewhere else entirely?

Project: https://github.com/Xerdi/comment2tex

Release: https://github.com/Xerdi/comment2tex/releases/tag/1.1

I have released comment2tex 1.1, a small literate-programming tool for weaving documentation from comments in source files.

Version 1.1 adds support for YAML and Makefiles alongside Lua and Bash. It also adds tangling for cases where the documented source should produce a separate runnable file.

YAML has an especially useful property here: no tangling step is required at all. Lines beginning with ## are treated as documentation by comment2tex, but they are still ordinary YAML comments. The annotated file therefore remains valid YAML and can be consumed directly by tools such as Ansible.

I have now used this approach on a real Ansible role that provisions a TeX Live mirror on AlmaLinux. The same role remains directly usable by Ansible and is woven into Xerdi’s Operator’s Handbook as typeset prose with numbered source listings.

The two images show the same source twice:

• first as the original annotated YAML;
• then as the corresponding page in the handbook.

comment2tex also uses this approach for much of its own manual. The documentation is woven from its actual:

• Lua implementation;
• Makefile;
• CI configuration in YAML;
• Bash test suite.

The main exception is the TeX source itself, for which the established DTX workflow remains the more natural solution.

So the package is increasingly documenting its own implementation, build process, tests and release infrastructure from the sources that actually perform that work.

I would be interested in feedback on both the package and the comment strategy, particularly from people already using literate programming or maintaining mixed-language TeX projects.

CTAN: https://ctan.org/pkg/comment2tex GitHub / release notes: https://github.com/Xerdi/comment2tex/releases/tag/1.1