ansible
ansible copied to clipboard
ansible
docs - add examples for dicts and nested dicts in main/argument_specs.yml
SUMMARY
The role argument validation documentation was missing some examples for list options with dicts and suboptions and dict options with suboptions as well as the author and version_added fields.
It now also documents the version_added field at the entrypoint level and options level.
It now also outputs the version_added at the entrypoint level.
Partly fixes: #77964
ISSUE TYPE
- Docs Pull Request
COMPONENT NAME
https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html#specification-format
Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at #docs:ansible.im and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see the Ansible calendar) and welcome additions to our weekly agenda items - scroll down to find the upcoming agenda and add a comment to put something new on that agenda.
@felixfontein as I'm at it:
get_role_man_text() in lib/ansible/cli/doc.py also knows about author and attributes. Should I add those as well? And how would attributes work for roles?
@ziegenberg yes, author definitely! About attributes: so far that has only been used for modules (or actions in general), not even for other plugin types, and for example antsibull-docs doesn't even support it for roles at the moment. So I would probably leave it away for now.
I amended and extended my commit. The changes are also reflected in the issue description.
For the wording of version_added I borrowed from here: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#documentation-fields
Yes, but the docsite does not.
It does now, btw. (At least it will for ansible-core 2.15.)
@ziegenberg @bcoca @felixfontein - sorry folks. It took me so long to review the PR backlog that we now have two PRs attempting to change this same area in the docs.
Can you review https://github.com/ansible/ansible/pull/80658 and see which PR has the most accurate and helpful information? I'm unsure which to merge (or if one of these PRs should subsume the added detail from the other PR.) Thanks for the help!
Thanks @ziegenberg for your patience. We're in the process of moving all docs to a new repo - ansible/ansible-documentation. Once that other PR is moved and merged, would be great if you can apply your PR there as well.
I think this can now be closed as it moved to ansible/ansible-documentation#13.