yaml4rst 0.1.2

Linting/reformatting tool for YAML files documented with inline RST

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, maintained in 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.

Usage

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.

Features

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

Known limitations

• 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 the debops.apt_install test case.

Authors

• Robin Schneider

License

GNU Affero General Public License v3 (AGPL-3.0)