Antsibull-docs does not include roles in collection documentation

[mpmackenna (Michael MacKenna)]

I am generating documentation for a collection. I used antsibull-docs to generate it. My modules get documented without issue, but my roles did not. I included the necessary argument_spec.yml file as indicated by the documentation but that did not seem to make a difference. I noticed the example site for sensu.sensu_go has a roles index. I also see documentation for a number of my roles when I browse the collection in ansible-navigator. I am not sure what I am missing. Any help is greatly appreciated!

This is the guide I followed.

Documenting collections — Ansible Documentation

This site has a role index.

https://docs.ansible.com/ansible/latest/collections/sensu/sensu_go/index.html#role-index

[felixfontein]

Did you name the file argument_spec.yml (as indicated in your post) or argument_specs.yml (as in the documentation you reference)? The plural s before the extension is important.

Also you should try looking at the role’s documentation with ansible-doc: ansible-doc --type role foo.bar.baz. If that works, then generating the docs with antsibull-docs should also work. (Assuming you are not using a very old version of ansible-core that doesn’t support role documentation - but then ansible-doc --type role won’t work either.)

[felixfontein]

(Here’s an example from my own collection: ansible-acme/roles/acme_certificate/meta/argument_specs.yml at main · felixfontein/ansible-acme · GitHub - and here’s one from sensu.sensu_go: sensu-go-ansible/roles/agent/meta/argument_specs.yml at master · sensu/sensu-go-ansible · GitHub)