Reformat documentation with 'andebox yaml-doc'

[felixfontein]

SUMMARY

Reformat the YAML documentation embedded into Python files with andebox.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

various

[github-actions]

Docs Build 📝

Thank you for contribution!✨

This PR has been merged and the docs are now incorporated into main:
https://ansible-collections.github.io/community.docker/branch/main

[russoz]

Thanks for using andebox, as you noticed it is far from perfect - it will solve most of the problem, but still some quirks. This action in andebox is largly dependent on ruamel.yaml, so I am considering submitting bug reports and feature requests to them later on. For now this is good enough to get going.

[felixfontein]

I did look a bit at how andebox works internally and noticed that it's basically a ruamel.yaml problem, and there doesn't seem to be obvious configurations for it. The good thing is that the examples here are reproducers of the problems ;)

For example:

content = r"""
- a:
    # Comment
    b: c
    # Comment

- a:
    - d: e
      # Comment
      f: g
      # Comment
    - h: j
      # Comment
      k: l

- a:
    - foo
      # Comment
    - baz
      # Comment
"""
from ruamel.yaml import YAML
from io import StringIO
yaml = YAML(typ='rt')
yaml.preserve_quotes = True
yaml.indent(mapping=2, sequence=4, offset=2)
yaml.explicit_start = False
yaml.width = 120
yaml.top_level_colon_align = False
yaml.compact_seq_seq = False
data = yaml.load(content)
output = StringIO()
yaml.dump(data, output)
print(output.getvalue())

This results in

  - a:
    # Comment
      b: c
    # Comment

  - a:
      - d: e
      # Comment
        f: g
      # Comment
      - h: j
      # Comment
        k: l

  - a:
      - foo
      # Comment
      - baz
      # Comment

printed. At least in the first two items the comments should be indented by two more spaces. In the third one I guess it is debatable...