@ctreatma The RETURN, EXAMPLES and DOCUMENTAITON are (and always were) generated with [ansible-specdoc](https://github.com/linode/ansible-specdoc) from SPECDOC_META variable in each module. SPECDOC_META is put together from `result_sample`, `specdoc_examples` and `module_spec`. You can see it for example in the metal_gateway module from this branch:
The RETURN in particular is generated from result_sample.
The result_sample is handwritten. We tried to copypaste output samples verbatim from Ansible tests. Ansible output is yaml, so we kept it as string. However, ansible-specdoc did not just copy the result_sample to RETURN, but emitted this mess instead.
In this PR, I reformatted the strings to python objects, which then ansible-specdoc transforms to valid yaml. This means that in order to write result_sample for new module, we'll have to transcribe example ansible output to Python format.
t0mk
commented
3 months ago
https://github.com/equinix-labs/ansible-collection-equinix/blob/fix_docs_for_galaxy/plugins/modules/metal_gateway.py#L222
The
RETURNin particular is generated fromresult_sample.The result_sample is handwritten. We tried to copypaste output samples verbatim from Ansible tests. Ansible output is yaml, so we kept it as string. However, ansible-specdoc did not just copy the result_sample to RETURN, but emitted this mess instead.
In this PR, I reformatted the strings to python objects, which then ansible-specdoc transforms to valid yaml. This means that in order to write result_sample for new module, we'll have to transcribe example ansible output to Python format.
_Originally posted by @t0mk in https://github.com/equinix-labs/ansible-collection-equinix/pull/164#discussion_r1512571860_