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)



Project details

Download files

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

Files for yaml4rst, version 0.1.6
Filename, size File type Python version Upload date Hashes
Filename, size yaml4rst-0.1.6-py3-none-any.whl (19.0 kB) File type Wheel Python version any Upload date Hashes View
Filename, size yaml4rst-0.1.6.tar.gz (135.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page