Filters - GenesisCoast/embedded-yaml-docs GitHub Wiki

In addition to the built-in Jinja2 filters the following filters have also been provided in the tool.

postfix

Adds a postfix to the supplied value.

prefix

Adds a prefix to the supplied value.

rejectattr_ifkey

Iterates through the collection and only rejects the item if the attribute both exists and it matches the supplied test.

rejectkey

Iterates through the collection and rejects the item it it contains the specified key. For use if the selectattr() function is returning false positives due to its truthiness behaviour.

selectattr_ifkey

Iterates through the collection and only selects the item if the attribute both exists and it matches the supplied test.

selectkey

Iterates through the collection and selects the item it it contains the specified key. For use if the selectattr() function is returning false positives due to its truthiness behaviour.

toyaml

Converts the specified object to a YAML string.

For example say we had an Azure DevOps pipeline with the following embedded docs. As part of the documentation we want to output the Description property and the Example property as a string.

azure-pipelines.yml

trigger: none
# Description:
#   We don't want to use a trigger because we want to exeucute our pipeline manually.
# Example:
#   pool:
#     vmImage: ubuntu-latest

And a Jinja2 template of:

template.j2

## {{ trigger.docs.Description }}

{{ trigger.docs.Example }}

We would expect the output to be:

## We don't want to use a trigger because we want to exeucute our pipeline manually.

pool:
  vmImage: ubuntu-latest

However, this actually fails as the Example property in the documentation is actually being parsed as a YAML object.

OrderedDict mutated during iteration

Traceback (most recent call last):
  File "c:\users\h.sanderson\appdata\local\programs\python\python38-32\lib\site-packages\src\__main__.py", line 156, in generate
    docs_parser.extract_docs(yaml, exclude_comments)
  File "c:\users\h.sanderson\appdata\local\programs\python\python38-32\lib\site-packages\src\yaml_docs_parser.py", line 115, in extract_docs
    self.extract_docs(val, parent=section, exclude_comments=exclude_comments)
  File "c:\users\h.sanderson\appdata\local\programs\python\python38-32\lib\site-packages\src\yaml_docs_parser.py", line 158, in extract_docs
    self.extract_docs(item, parent=section, exclude_comments=exclude_comments)
  File "c:\users\h.sanderson\appdata\local\programs\python\python38-32\lib\site-packages\src\yaml_docs_parser.py", line 110, in extract_docs
    for key in section.keys():
  File "c:\users\h.sanderson\appdata\local\programs\python\python38-32\lib\site-packages\ruamel\yaml\comments.py", line 589, in __iter__ 
    for x in self._mapping:
  File "c:\users\h.sanderson\appdata\local\programs\python\python38-32\lib\site-packages\ruamel\yaml\comments.py", line 822, in __iter__
    for x in ordereddict.__iter__(self):

RuntimeError: OrderedDict mutated during iteration

To fix this we need to convert the Example property from a YAML object back into a YAML string. This can be done by adding the toyaml filter to the Jinja2 expression.

template.j2

## {{ trigger.docs.Description }}

{{ trigger.docs.Example | toyaml }}

Our output now becomes:

## We don't want to use a trigger because we want to exeucute our pipeline manually.

pool:
  vmImage: ubuntu-latest