Return documentation fragments, the way forward

bcoca
Thu, 04 Sep 2025 15:18:23 +0000
Project Discussions

For ansible-core 2.20 we added the ability for modules to use ‘fragments’ to document ‘return’ documentation, something we’ve been able to do for a long time for ‘options’. add fragments to return by bcoca · Pull Request #72635 · ansible/ansible · GitHub

The main issue is that using this facility, which mirrors the existing one, is not backwards compatible and will result in an error when viewing the docs that use this. Mainly because ‘return’ had a simpler structure so it mixes with the fields and, which are equivalent to options but at the top level.

While attempting to fix that by backporting an ‘ignore fragments’ feature
[stable-2.19] ignore doc fragments in return by bcoca · Pull Request #85760 · ansible/ansible · GitHub some questions/suggestions were brought up .. that led to many others and now I’m at an impasse so I thought I would post here and see if someone can find a better solution.

Possible ways forward

A) backport fragment support,

the full feature or just enough to show warning, pros/cons are the same either way, both changers are about the same size and just as invasive.

pros

this ‘fixes’ compatibility issue and will actually display the full docs

cons

against our policy to backport features, breaks the user ‘contract’ by introducing new surfaces for bugs/attacks/etc

deciding ‘up to which version’ will be ‘fun’ and opens the door to ‘I’m still on 2.9, why didn’t you update that?’

B) reimplement as new top level var RETURN_FRAGMENTS

pros

previous versions will completely ignore

cons

new syntax to do same thing

docs won’t be correctly displayed on older versions and no hint that there are ‘missing’ fragments

C) reimplement as ‘fragment_return_option’

pros

previous versions will display the ‘fragment reference’ , which indicates there are more docs you don’t currently see

cons

new syntax to do same thing

confusing ‘return field’ that looks like normal fields but is not really a field

D) do nothing

pros

nothing to backport, no chance for new bugs/errors/etc

cons

collections using return fragments are limited to core >=2.20

E) remove return fragments and go back to drawing board

pros

punting

cons

punting

F) Something else?

How else could we resovle this?

20 posts - 4 participants