[spetrosi]

SUMMARY

Document the optional return: key for roles in the role argument-spec "Specification format" section.

Roles can document the variables they set via a return: block per entry point in meta/argument_specs.yml, using the same format as module return values. ansible-doc and antsibull-docs render it as a "Return Variables" table. This documents the field and its sub-keys (description, type, elements, returned, sample, choices, version_added, nested contains), and adds a return: block to the sample specification.

Marked draft pending the ecosystem discussion linked below. This is the documentation piece of a cross-repo effort:

• antsibull-docs (render the table): Render a "Return Variables" table for roles ansible-community/antsibull-docs#492
• ansible-lint (accept the key in the schema): feat: allow return values in role argument_specs schema ansible-lint#5213
• ansible-core (show it in ansible-doc text output): ansible-doc - show role return values in text output ansible#87686

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst

ADDITIONAL INFORMATION

Discussion: https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469
Refs: ansible-community/antsibull-docs#491

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.