Skip to main content

Linting/reformatting tool for YAML files documented with inline RST

Project description

Build Status Read the Docs CII Best Practices Code Coverage Status
Version License Python versions dev status pypi monthly downloads

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

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.


  • GitHub (primary repo with issue tracker)




GNU Affero General Public License v3 (AGPL-3.0)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

yaml4rst-0.1.6.tar.gz (135.4 kB view hashes)

Uploaded source

Built Distribution

yaml4rst-0.1.6-py3-none-any.whl (19.0 kB view hashes)

Uploaded any

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page