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?
Well yeah there is no need to use the return key after all. I like set_variables!
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.
If the documentation is supposed to only be used for
set_fact+cacheableandansible_facts, I thinkset_variablesis still overly broad and going to be confusing/misused. Something likeset_cacheable_factswould 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
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
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_variablestoo). 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.
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.
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.
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/
Slides - 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
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 
Thank you for your kind words.
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.
I care about supported to be able to publish my collection docs to official Ansible docs
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.
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, I was told that it’s possible to publish docs there without the need to make it part of ansible community package.
I didn’t say anything shouldn’t be documented. The proposal pertains to facts.
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.
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, that might be the source of the misunderstanding.
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. 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, 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.
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)
Can we tag other parties here and ask for their opinion, or is there a better channel?