Files identified in the description:

• lib/ansible/playbook/role/__init__.py

If these files are incorrect, please update the component name section of the description or use the component bot command.

cc @felixfontein @samccann @newswangerd

👍 for adding that.

Depending on the role a more extensive document would also be useful (something with sections and text between examples), but that's a bit too much IMO - ansible-doc shouldn't become an arbitrary documentation rendering engine.

@felixfontein a role within a collection could probably do that already with the collection-level docs support we have now. But that doesn't help standalone roles...And I agree- too much for ansible-doc.

Can you point me at the collection level docs you're talking about?

https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#collections-doc-dir

Notice there is an unfortunate catch-22 - if you want docs like these in docs.ansible.com, you have to write in .rst in a specific directory. If you want docs like these on AutomationHub/GalaxyNG - you have to write in md in a different directory (my guess is it works on galaxyNG but I haven't poked around to verify that).

Ah right, but those would be really at the collection level, not part of the docs shown for a role in a collection (either via ansible-doc or antsibull-docs).

correct

ansible-core: #82671
ansible-lint: ansible/ansible-lint#4019
antsibull-docs: ansible-community/antsibull-docs#244

@evgeni Any updates on this?

@ssbarnea this is waiting on the Core team, as PRs exists, but the PR for ansible-core needs to be merged first. Right now #82671 has no review and there's no indication whether it even has a chance to get merged eventually.