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
details.
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.
Refer to input_files
and output_files
in the tests directory for
automatically tested examples of input and output files.
Note that for continues usage yaml4rst is invoked from debops-optimize when yaml4rst is installed so you might want to try debops-optimize.
Checks for:
- Reasonable variable namespace
- Undocumented variables
Automatically fixes:
- 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
NotImplementedError
exception 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
yaml4rst
will add missing folds for sections and variables anyway. Refer to the Makefile (prepare-real-data
target) where such a workaround is used for integration testing. Note that this is not perfect as can be seen on thedebops.apt_install
test case.
- GitHub (primary repo with issue tracker)