use modern role documentation

[evgeni]

SUMMARY

ansible-core 2.11 supports role argument specs (https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#role-argument-validation, https://steampunk.si/blog/ansible-role-argument-specification/)
and the surrounding tooling is now also getting support for that (ansible-community/antsibull-build#272, ansible-community/antsibull-changelog#55) which means we can better automate our documentation generation :)

ISSUE TYPE

• Feature Idea

[evgeni]

an example can be found in sensu/sensu-go-ansible#289

[evgeni]

@wbclark to raise his issues/concerns :)

[wbclark]

1. this does not need to replace the complete README.md text for the role but can replace only e.g. the block that documents each parameter

2. we need some method to dynamically generate that parameters block of README.md contents from the modern role documentation

3. how does the current role interact with ansible-doc (does it?)

4. let's follow up on Generate role documentation ansible-community/antsibull-build#272 about looking for and incorporating a README.md

[wbclark]

In https://github.com/theforeman/foreman-ansible-modules/tree/develop/roles/activation_keys#role-variables we have role variables sorted into sections:

• The main data structure for this role is the list of foreman_activation_keys. Each activation_key requires the following fields:
• The following fields are required for an activation key but have defaults which make them optional for this role:
• The following fields are optional in the sense that the server will use default values when they are omitted:
• The following fields are optional and will be omitted by default:

It might be nice to have some metadata tag associated with each role variable so that they can be grouped under different headings in the documentation. I'll suggest this on the antsibull PR

[evgeni]

FWIW, I think the metadata structure comes from Ansible, not antsibull.