[Bug]: Modules docs don't render properly in Ansible Galaxy web

[t0mk]

Expected Behavior

The generated dostrings should be in proper format for Ansible Galaxy. The Galaxy website should parse the DOCUMENTATION etc markdown and render nice html.

Basically, it seems that with the currecnt version of Galaxy web, the format changed and ansible-specdoc-generated docs are somehow wrong.

Thanks for your work on this useful project!

Actual Behavior

Only "Synopsis" is rendered.

https://galaxy.ansible.com/ui/repo/published/linode/cloud/content/module/instance/

Steps to Reproduce

No response

Error Output

No response

[jriddle-linode]

Thanks for reporting this, I've created a critical ticket internally and we'll tag this issue in the PR.

[t0mk]

@jriddle-linode

I looked at it a bit and in our case the problem was rendered RETURN - it was quoted a lot, quite messy and maybe wasn't valid YAML.
https://github.com/equinix-labs/ansible-collection-equinix/blob/main/plugins/modules/metal_project.py#L76

ansible-docs tests the DOCUMENTATION and RETURN by loading it as an Ansible yaml:
https://github.com/ansible/ansible/blob/devel/lib/ansible/parsing/plugin_docs.py#L156

We had quite a mess rendered there, so I'm guessing ansible-doc was silently failing and skipping the galaxy docs render. I am not sure why your module documentation isn't rendered. I noticed you don't have DOCUMENTATION etc even injected in commited code in ansible_linode.

I think this bug is a bit invalid, but it would be a nice touch if ansible-specdoc validated that injected DOCUMENTAION, EXAMPLES and RETURN are valid yaml.