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.