Return doccumentation fragments, the way forward

Project Discussions
, , , ,
1

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

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?

2 Likes
2

Note that B) has another con: if you mix return fragments with documentation in the module, like showing a version_added for a return value from a return fragment in RETURN, then it will result in documentation you cannot look at with ansible-doc. (Unless such ‘merges’ also have to be moved to RETURN_FRAGMENTS, which then means that return values can be specified both in RETURN and RETURN_FRAGMENTS, which in turn opens more cans of worms…)

Regarding punting / E and backporting / A: I’d prefer to have this feature in as early as possible, so we can start using it sooner. Depending on how it goes (i.e. if older ansible-doc versions cannot show docs, or show only incomplete docs), it will take some years until collections dropped support for all ansible-core versions that cannot handle return fragments and can start using that feature. It would be nice to reduce this amount of years to a very small number (preferably 0, which is quite unlikely though :slight_smile: ).

I’ve been trying out return fragments with community.crypto btw (and started stumbling on some of these problems), in case anyone wants to take a look: [WIP] Use return doc fragments by felixfontein · Pull Request #951 · ansible-collections/community.crypto · GitHub

3

As per B) the new variable can have diff sections, 1 for fragment list, 1 for overrides, any reimplementation should take these things into account. And, yes, this opens to duplication, one reason i’m not sure this is a good option.

4

How about option E: make ansible-doc not crash if it finds extends_documentation_fragment whose value is a list, while displaying a warning (i.e. basically [stable-2.19] ignore doc fragments in return by bcoca · Pull Request #85760 · ansible/ansible · GitHub)?

My main problem with that solution so far was [stable-2.19] ignore doc fragments in return by bcoca · Pull Request #85760 · ansible/ansible · GitHub, but there’s a good workaround for that: create another doc return fragment (and mark it as private), one for each module that needs such ‘updates’, put the updates there, and then use it only in that module. (See [WIP] Use return doc fragments by felixfontein · Pull Request #951 · ansible-collections/community.crypto · GitHub for how this looks like.)

As long as the warning is shown, users know that the documentation isn’t complete, but they can at least view the remainder of the docs. I would display the warning in the rendered text docs as well, though (maybe in the return value doc section), so that the warning is harder to miss.

5

E) still has a backwards compatibility issue and it is technically a ‘feature’, something that makes it an even harder sell to the stable maintainers.

6

I think it’s mostly a bugfix, since it prevents a crash. The warning part can be seen as a feature, but I personally think that it is OK since it’s a big help for users, which would otherwise not know that something is amiss and was ignored. (I tried the current warning, it’s basically impossible to see it without scrolling up after exiting the help viewer.)