ansible-doc fix YAML examples rendering

[bcoca]

Also fixing ansible-test

ISSUE TYPE

• Bugfix Pull Request

ADDITIONAL INFORMATION

https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048
https://github.com/scaleway/ansible/blob/ruff_check/plugins/inventory/scaleway.yml

[sivel]

In case you want to look at this one too, and only applies to modules:

ansible/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py

Lines 1082 to 1086 in 01ca9b1

	dummy, errors, traces = parse_yaml(examples_raw,
	examples_lineno,
	self.name, 'EXAMPLES',
	load_all=True,
	ansible_loader=True)

That always assumes that EXAMPLES will be a string.

[bcoca]

@sivel, looking at that, it ONLY checks modules, it should really check most plugins ... might need it's own PR

[bcoca]

cc @felixfontein

[mattclay]

Is there a reason we're using the AnsibleLoader and AnsibleDumper instead of the normal loader and dumper?

[bcoca]

!vault and !unsafe in examples break otherwise

[mattclay]

Examples should only be accepted as text, not structured data. Attempting to load them as anything other than text loses comments, formatting and !unsafe, as well as complicates the loading and dumping. Using the normal YAML loader and dumper will allow non-text examples to pass through as long as they don't use ansible specific tags. The validate-modules sanity test should be updated to report an error (if it doesn't already) when the examples are not text, so that developers know to correct their examples.

In the future we could implement a feature to allow validating the text examples in whatever format(s) we'd like to support, such as YAML, but that's not something we should try to design now.

[bcoca]

@mattclay @sivel ping

[mattclay]

There doesn't appear to be a good reason to add support to ansible-doc for dumping Ansible-specific types. Switching to the standard YAML loader for sidecar will avoid the need for that.

Looking at collections on Galaxy, there's no usage of Ansible YAML tags in sidecar docs. Even if someone was using them, the docs are already broken -- either generating tracebacks or rendering incorrectly. So we shouldn't need to worry about introducing new issues by changing the loader.

[bcoca]

This is not a new feature but fixing the exiting feature to align with what would be the logical expectation, that ansible documentation can handle ansible specific yaml.

Also, I'm sure no one is using a feature that would currently break their docs, that does not mean they have not tried nor want to.

[mattclay]

Examples should only be accepted as text, not structured data. Attempting to load them as anything other than text loses comments, formatting and !unsafe, as well as complicates the loading and dumping. Using the normal YAML loader and dumper will allow non-text examples to pass through as long as they don't use ansible specific tags. The validate-modules sanity test should be updated to report an error (if it doesn't already) when the examples are not text, so that developers know to correct their examples.

In the future we could implement a feature to allow validating the text examples in whatever format(s) we'd like to support, such as YAML, but that's not something we should try to design now.