yaml4rst is a linting/checking/reformatting tool for YAML files documented with inline RST which goes hand in hand with yaml2rst.
It has been written to help with keeping the
defaults/main.yml file in
Ansible roles of DebOps up-to-date and to assist with writing or
including new roles. DebOps uses Sphinx to generate Ansible role documentation
which also includes the default role variables. Refer to debops/docs for
The typical use case for this program is to improve the defaults YAML file of Ansible roles.
The recommended way to do this is to commit all your changes in the repository of the role, then run:
yaml4rst -e 'ansible_full_role_name=ROLE_OWNER.ROLE_NAME' defaults/main.yml -i
from the root of the role repository. Be sure to replace
ROLE_OWNER.ROLE_NAME with the particular Ansible role name.
This will check and reformat the
defaults/main.yml file in place.
Now you can check the reformatted file with a diffing/editing tool of your choosing
and fix any warning which
yaml4rst might have emitted.
output_files in the tests directory for
automatically tested examples of input and output files.
- Reasonable variable namespace
- Undocumented variables
- RST sections which are not folds
- Undocumented variables (adds a FIXME for the user)
- Documented variables which are not folds
- YAML documents without a defined header
- Spacing between variables and sections
Does not handle folds with implicit level and missing closing fold marker.
Status: Should be doable but currently not needed nor implemented. A
NotImplementedErrorexception is thrown which causes the CLI program to terminate immediately with an error and reference to this section.
As workaround just strip out the opening folds with your favorite editor as
yaml4rstwill add missing folds for sections and variables anyway. Refer to the Makefile (
prepare-real-datatarget) where such a workaround is used for integration testing. Note that this is not perfect as can be seen on the