Document play argument validation

[s-hertel]

Adding some documentation for ansible/ansible#85763.

I'm not sure if the playbook introduction is the best place to document this. I'm guessing we might want to reference this feature on multiple pages.

The 'Specification Format' section is largely copied from the role argument specification documentation, but I removed fields that are strictly for documentation purposes (other than description) since ansible-doc doesn't do anything with this feature yet.

[s-hertel]

I could make this a snippet, and include it in the playbooks intro and any additional locations.

Facts gathered at the play level (i.e. gather_facts: true) can be validated, so maybe https://github.com/ansible/ansible-documentation/blob/devel/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst could reference it even though the documentation is a little more general than that.

A variety of variable sources can be validated, so https://github.com/ansible/ansible-documentation/blob/devel/docs/docsite/rst/playbook_guide/playbooks_variables.rst could reference it even though the documentation covers additional variable sources.

... anywhere else? None of the pages seems like a perfect fit, so any suggestions are welcome.

[samccann]

Asking the hivemind for advice - https://forum.ansible.com/t/where-should-we-document-the-new-play-argspec/44588

:-)

[samccann]

My initial suggestion is to not use snippets. Most contributors don't know how to use them and it makes it unsustainable over the long term. We have a hodgepodge of them now in the docs that we should actually remove.

So far, where you have it documented in this PR makes sense to me and we could put links to this section from the other places you mention in your comments. But let's see if we get other ideas from the forum post.

[StSchnell]

Hello Sandra [@samccann],
I'm not quite sure what you mean by saying that snippets should no longer be used. Do you mean the examples? If yes, from my perspective I can only say that the snippets/examples often help me understand how to use something. I would consider it a loss if these were to disappear.
Best regards
Stefan

[s-hertel]

@StSchnell When I used the word 'snippet', I just meant the organization of the documentation (https://github.com/ansible/ansible-documentation/tree/devel/docs/docsite/rst/shared_snippets), and nothing to do with the contents of the documentation.

[s-hertel]

@samccann I grep for everything, so I'm just trying to figure out where people organically will look for documentation for this feature. I'd love to not reference it on multiple pages because then I really have to use grep to find what I'm looking for. If this is a fine location to document it, I'm happy with it.

[oraNod]

@s-hertel 👋 Thanks for the patience as I've been trying to get round to reviewing this in a bit more detail. I'll add some more comments soon but wanted to provide my thoughts on where this info might fit.

After looking again, I think maybe somewhere between the "Interactive input: prompts" and "Using variables" sections.

I guess both prompts and arg validation are kind of related. And, like the "Module defaults" section, these docs are about a play-level keyword. So it keeps things together conceptually.

[oraNod]

Some suggestions for the top part of the docs for a bit more clarity.

I think it might be worth explaining some of the benefits to the play argument validation here too. Does this sound correct?

Play argument validation takes place immediately after fact gathering and lets you check if you've passed incorrect values before executing your playbook. By defining specifications for arguments, such as required versus optional arguments, data types, and parameter options, you describe the expected arguments for playbooks in a structured format.

[oraNod]

@s-hertel Hi, should we go ahead and merge this since 2.20.0 is now available? https://github.com/ansible/ansible/blob/v2.20.0/changelogs/CHANGELOG-v2.20.rst

[s-hertel]

After looking again, I think maybe somewhere between the "Interactive input: prompts" and "Using variables" sections.

How about adding this after the following in https://docs.ansible.com/ansible/devel/playbook_guide/:

Interactive input: prompts
Using variables
Discovering variables: facts and magic variables

All of those sections include ways of providing variables that can be validated using validate_argspec play keyword.

[oraNod]

After looking again, I think maybe somewhere between the "Interactive input: prompts" and "Using variables" sections.

How about adding this after the following in https://docs.ansible.com/ansible/devel/playbook_guide/:

Interactive input: prompts Using variables Discovering variables: facts and magic variables

All of those sections include ways of providing variables that can be validated using validate_argspec play keyword.

@s-hertel That sounds good to me!

[oraNod]

Looks good. Thanks @s-hertel

[patchback]

Backport to stable-2.20: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-2.20/efcffedf864d018b015e6ace5f5c91f347630670/pr-3079

Backported as #3227

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.