# Proposal: document role "return variables" in argument\_specs.yml (like module RETURN) **URL:** \ **Category:** Project Discussions\ **Tags:** rhel, role, documentation, antsibull, ansible-lint, linux-system-roles, ansible-core\ **Created:** [October 13, 2026, 8:20am UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469 "2026-10-13T08:20:48Z")\ **Posts on this page:** 18\ **Page:** 2
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [October 16, 2026, 11:22am UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/21 "2026-10-16T11:22:32Z")
But maybe they will not return variables, but behave like modules (where you have to use `register`)? In that case, `return` should likely be used for that, which would be a breaking change if `return` is already used for this. Maybe another key, like `set_variables`, should be used instead? ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 16, 2026, 11:38am UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/22 "2026-10-16T11:38:51Z")
Well yeah there is no need to use the return key after all. I like set\_variables! ---
**Author:** ![shertel](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/shertel/32/1241_2.png) [@shertel](https://forum.ansible.com/u/shertel)\ **Post date:** [October 16, 2026, 4:35pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/23 "2026-10-16T16:35:33Z")
> If roles ever do get a way to return variables, this new way can reuse the return: key that’s it. > I don’t think we bring any extra future burden by supporting return key to document variables that roles set. If role “return” documentation is added based off a super narrow, non-standard meaning of “return”, then adding that feature in a conventional sense (if it happens) is more difficult for core and could negatively impact the documentation (e.g. might need to call it something other than “return” or maintain multiple schema versions) or the feature (e.g. might keep parity with existing role documentation, instead of designing how it should work top-down). > Role won’t enforce any extra validation of the return content, there’s no need to validate it because this is not something that users can do mistakes with. The caller of the role controls whether or not validation occurs. If you use a wrapper role + helper roles, the wrapper role has control over how the helper roles are invoked, and the user can choose whether to validate data they can’t control from the wrapper role. I don’t see the harm is validating the variables though - since it’s out of the user’s control it should always be valid. The benefit is keeping the documentation in sync with role development. I know my suggestion to use the role argument spec is also limited, but it uses official tooling already available and seems more flexible than the proposal to me. (As an aside, I noticed your ansible-documentation pull request adds “choices”, which is an argument spec thing, not a return documentation thing.) > Well yeah there is no need to use the return key after all. I like set\_variables! If the documentation is supposed to only be used for `set_fact` + `cacheable` and `ansible_facts`, I think `set_variables` is still overly broad and going to be confusing/misused. Something like `set_cacheable_facts` would seem clearer to me. I do see the benefit to documenting facts, and agree it’s a special case, but I think the documentation would be more helpful if it was intended for variables of any source (in which case, I like `set_variables` too). The proposal doesn’t address general needs of roles very well. As the caller of a role, I want to know the variables it sets and how, as this can impact how I need to call the role and how it impacts the play earlier and later on. ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 19, 2026, 1:48pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/24 "2026-10-19T13:48:47Z")
> If the documentation is supposed to only be used for `set_fact` + `cacheable` and `ansible_facts`, I think `set_variables` is still overly broad and going to be confusing/misused. Something like `set_cacheable_facts` would seem clearer to me. I think setting `cacheable: true` is not always necessary and may be an overkill sometimes. Users can re-register with `cacheable: true`, or save content to a file/facts\_file if they needed content to persist. So rather just set\_fact and ansible\_facts. Examples: rolename\_reboot\_needed - [GitHub - linux-system-roles/bootloader: Ansible role for bootloader and kernel command line management · GitHub](https://github.com/linux-system-roles/bootloader#bootloader_reboot_needed) rolename\_facts - linux-system-roles/bootloader#bootloader\_facts and linux-system-roles/ha\_cluster#variables-exported-by-the-role The rolename\_facts variable can be pretty complicated because role saves much configuration within a single variable. So documenting it within a handy table that includes variable type, choises, etc. is what I want. Right now, I cannot document variables “returned” by the role with a handy table, like modules can. Instead, I only can add such documentation into the Notes section with weird indentation, like I attempt here - [docs: draft preview of new argument\_specs-based documentation by spetrosi · Pull Request #443 · linux-system-roles/ha\_cluster · GitHub](https://github.com/linux-system-roles/ha_cluster/pull/443/changes#diff-54476ea7257304a760f273caebc0ca7ae6c3f599571bf52891d260fa99ccfe95R78-R134) I want to be able to document those with yaml inside argument\_specs and auto-generate table from it. > I do see the benefit to documenting facts, and agree it’s a special case, but I think the documentation would be more helpful if it was intended for variables of any source (in which case, I like `set_variables` too). The proposal doesn’t address general needs of roles very well. As the caller of a role, I want to know the variables it sets and how, as this can impact how I need to call the role and how it impacts the play earlier and later on. This suggestion rather works around the issue that roles don’t have a proper way to return variables. Implementing a working solution in roles is a separate big issue that I don’t foresee being implemented, so for now I want to be able to workaround it with docs at least. Well-formatted docs generated automatically from yaml in argument\_specs.yml. ---
**Author:** ![kks](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/kks/32/10352_2.png) [@kks](https://forum.ansible.com/u/kks)\ **Post date:** [October 19, 2026, 2:06pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/25 "2026-10-19T14:06:20Z")
> [@shertel](#): > > I do see the benefit to documenting facts All the side effects of ansible role should be documented, as this is the only way ansible role could change something “outside” of it. That is the whole point to run ansible role in the first place - side effects it can provide. ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [October 19, 2026, 2:15pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/26 "2026-10-19T14:15:33Z")
I would argue that roles do not create ‘side effects’ but ‘purposeful effects’ and that the category is so broad it is very hard to structure into the ‘spec’ documentation, that is why role documentation (readme) exists. While ‘variables’ might be a lot easier to structure than ‘general effects’, it is still a complex issue as a mentioned above, just scope alone can make the ‘return’ documentation a nightmare. ---
**Author:** ![kks](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/kks/32/10352_2.png) [@kks](https://forum.ansible.com/u/kks)\ **Post date:** [October 19, 2026, 2:26pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/27 "2026-10-19T14:26:15Z")
> [@bcoca](#): > > that the category is so broad it is very hard to structure into the ‘spec’ documentation, that is why role documentation (readme) exists. Could not agree more. At the moment there is no way (nor good nor bad) to keep argument\_specs (role documentation and webpages are generated from this file) and readme.md (actual role documentation) aligned. Initial proposal in this thread is just a small step in the right direction (make both files more or less aligned). I also had some suggestions how to make this alignment happen using ansible-docsmith: Talk page [https://cfp.cfgmgmtcamp.org/ghent2026/talk/UJHJE7/](https://cfp.cfgmgmtcamp.org/ghent2026/talk/UJHJE7/) Slides - [https://cfp.cfgmgmtcamp.org/media/ghent2026/submissions/UJHJE7/resources/ansible-docsmith\_-\_ultimate\_tool\_to\_document\_ansi\_LyVf0hQ.pdf](https://cfp.cfgmgmtcamp.org/media/ghent2026/submissions/UJHJE7/resources/ansible-docsmith_-_ultimate_tool_to_document_ansi_LyVf0hQ.pdf) Recording - [https://www.youtube.com/watch?v=yNm9Aut\_7Zk](https://www.youtube.com/watch?v=yNm9Aut_7Zk) ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 19, 2026, 4:35pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/28 "2026-10-19T16:35:47Z")
> While ‘variables’ might be a lot easier to structure than ‘general effects’, it is still a complex issue as a mentioned above, just scope alone can make the ‘return’ documentation a nightmare. Richard has suggested above to add an additional key that would define HOW the variable is set. Can be `scope:`. Or, if this is too complex, just let users describe it in plain text. > At the moment there is no way (nor good nor bad) to keep argument\_specs (role documentation and webpages are generated from this file) and readme.md (actual role documentation) aligned. I was trying to solve this by keeping all information that role needs within the argument\_specs.yml `notes` and `description` sections. Then, have the HTML generated from argument\_spec (using the workaround that converts role to an collection first, and then generate docs for a collection using sphinx - this results in an HTML in addition to RST). Then, convert HTML to MD. If sphinx could generate MD right away, in addition to RST, TXT, HTML, it would be great. But for now, convert HTML to MD is the way for me. I like the ansible-docsmith presentation, I will definitely look at using it. I liked how you used extra hidden entry points, I might use it instead of a custom `set_variables`. I’d prefer to have a supported `set_variables` of course 🙂 ---
**Author:** ![kks](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/kks/32/10352_2.png) [@kks](https://forum.ansible.com/u/kks)\ **Post date:** [October 19, 2026, 5:42pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/29 "2026-10-19T17:42:20Z")
> [@spetrosi](#): > > I like the ansible-docsmith presentation, I will definitely look at using it. I liked how you used extra hidden entry points, I might use it instead of a custom `set_variables` Thank you for your kind words. > [@spetrosi](#): > > I’d prefer to have a supported `set_variables` of course 🙂 At some point I’ve decided that “supported” just does not provides any value to me. Bit “simple” and “quick” do provide value to me. Everyone is in different situation of course. ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 19, 2026, 6:02pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/30 "2026-10-19T18:02:39Z")
I care about supported to be able to publish my collection docs to official Ansible docs ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [October 19, 2026, 9:17pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/31 "2026-10-19T21:17:53Z")
The ‘official docs’ should not matter as much .. .if galaxy did a good job of displaying the docs. Also the reason so many collections push to be in the ‘ansible’ community package. ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 20, 2026, 7:19am UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/32 "2026-10-20T07:19:19Z")
Yeah, the fact that Galaxy doesn’t publish docs generated from argument\_specs.yml, and doesn’t render RST format surprised me. I see many collections outside of the ansible namespace in [Collection Index — Ansible Community Documentation](https://docs.ansible.com/projects/ansible/latest/collections/index.html), I was told that it’s possible to publish docs there without the need to make it part of ansible community package. ---
**Author:** ![shertel](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/shertel/32/1241_2.png) [@shertel](https://forum.ansible.com/u/shertel)\ **Post date:** [October 20, 2026, 3:48pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/33 "2026-10-20T15:48:22Z")
I didn’t say anything shouldn’t be documented. The proposal pertains to facts. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [October 20, 2026, 5:43pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/34 "2026-10-20T17:43:56Z")
> [@spetrosi](#): > > I was told that it’s possible to publish docs there without the need to make it part of ansible community package. I’m not sure who told you that, but right now that’s not correct. The collections documented there are exactly the collections that are part of the [Ansible community package](https://pypi.org/project/ansible/). ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [October 20, 2026, 6:01pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/35 "2026-10-20T18:01:59Z")
It is not currently possible to publish there w/o being part of the community package, but it is a capability that has been proposed as an alternative to adding it to [galaxy.ansible.com](http://galaxy.ansible.com), that might be the source of the misunderstanding. ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 29, 2026, 1:55pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/36 "2026-10-29T13:55:09Z")
> It is not currently possible to publish there w/o being part of the community package Yeah that’s true, sorry for the confusion. The plan was a little different - publish docs as a new section under ecosystem at [Ansible ecosystem | Ansible documentation](https://docs.ansible.com/ecosystem.html). I didn’t understand it myself hense the confusion. I’ve bumped upon [role argument spec: allow for notes, seealso, requirements, version\_added like with plugins · Issue #81735 · ansible/ansible · GitHub](https://github.com/ansible/ansible/issues/81735), which has Felix’s PR attached, which has been closed. So ansible-lint schema for argument\_specs doesn’t allow Notes, even though antsibull-docs builds them completely fine. This is a big mistake IMO. And another blocker for me because I wanted to use Notes section for technical details. And what about this issue? Brian mentioned that it’s a complex issue, but I see no reasons to not make it possible to document this complexity within argument\_specs. Keeping in mind that this will be an optional field and won’t break anything. ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [October 30, 2026, 3:22pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/37 "2026-10-30T15:22:18Z")
Technologically it is simple to add to ansible-doc, but we really cannot just do it as we need to coordinate and get buy in from from awx/galaxy-ui/galaxy-importer/lint/devtools/etc and community (which is probably the easy part) ---
**Author:** ![spetrosi](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/spetrosi/32/11328_2.png) [@spetrosi](https://forum.ansible.com/u/spetrosi)\ **Post date:** [October 30, 2026, 4:01pm UTC](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469/38 "2026-10-30T16:01:00Z")
Can we tag other parties here and ask for their opinion, or is there a better channel? [Previous page](https://forum.ansible.com/t/proposal-document-role-return-variables-in-argument-specs-yml-like-module-return/46469.md?page=1)