Document play argument validation (#3079)

* Document play argument spec validation

* Update docs/docsite/rst/playbook_guide/playbooks_intro.rst

Co-authored-by: Don Naro <[email protected]>

* Move the play-level argument spec validation following the sections on variables

---------

Co-authored-by: Don Naro <[email protected]>

Author: s-hertel

docs/docsite/rst/playbook_guide/playbooks.rst

@@ -37,4 +37,5 @@ There are multiple ways to organize playbooks and the files they include, and we
    playbooks_prompts
    playbooks_variables
    playbooks_vars_facts
+   playbooks_variables_validation
    guide_rolling_upgrade

docs/docsite/rst/playbook_guide/playbooks_variables_validation.rst

@@ -0,0 +1,116 @@
+.. _play_argument_validation:
+
+Play Argument Validation
+------------------------
+
+Beginning in version 2.20, you can enable argument validation using the play keyword ``validate_argspec``. This adds a :ansplugin:`validate_argument_spec <ansible.builtin.validate_argument_spec#module>` task following play-level fact gathering. This feature is tech preview.
+
+Play argument validation has two main parts:
+
+* The ``validate_argspec`` keyword.
+* A ``.meta.yml`` file that defines argument specifications.
+
+To enable play argument validation you:
+
+#. Define the argument specification identifier by setting a value for the ``validate_argspec`` keyword. You can set the value to ``True`` to use the play ``name`` or you can set the value to a string.
+#. Provide a valid argument specification in a ``<playbook_name>.meta.yml`` file in the same directory as the playbook.
+
+The following example provides a valid, empty argument specification named ``setup webserver`` for the playbook ``create_webserver.yml``:
+
+.. code-block:: yaml
+
+   # create_webserver.meta.yml
+   argument_specs:
+     setup webserver:
+       options: {}
+
+In the following playbook, both plays validate the play arguments against the ``setup webserver`` arguments:
+
+.. code-block:: yaml
+
+   # create_webserver.yml
+   - name: setup webserver
+     hosts: all
+     validate_argspec: True
+
+   - hosts: all
+     validate_argspec: setup webserver
+
+Specification Format
+--------------------
+
+The play argument specification must be defined in a top-level ``argument_specs`` block within the playbook's ``.meta.yml`` file. All fields are lowercase.
+
+:argument-spec-name:
+
+    * The name of the play or argument specification.
+
+    :description:
+
+        * A description of the play that may contain multiple lines.
+        * This can be a single string or a list of strings.
+
+    :options:
+
+        * This section defines the dictionary of play arguments.
+        * For each play option (argument), you may include:
+
+        :option-name:
+
+            * The name of the option/argument (required).
+
+        :description:
+
+            * Detailed explanation of what this option does. It should be written in full sentences.
+            * This can be a single string or a list of strings.
+
+        :type:
+
+            * The data type of the option. See :ref:`Argument spec <argument_spec>` for allowed values for ``type``. The default is ``str``.
+            * If an option is of type ``list``, ``elements`` should be specified.
+
+        :required:
+
+            * Only needed if ``true``.
+            * If missing, the option is not required.
+
+        :choices:
+
+            * List of option values.
+            * Should be absent if empty.
+
+        :elements:
+
+            * Specifies the data type for list elements when the type is ``list``.
+
+        :options:
+
+            * If this option takes a dict or list of dicts, you can define the structure here.
+
+Sample Specification
+--------------------
+
+.. code-block:: yaml
+
+   # create_webservers.meta.yml
+   description: Set up basic HTTPS-enabled webserver to serve content from a specified document root.
+   argument_specs:
+     setup webserver:
+       options:
+         document_root:
+           description: Path to the directory containing static web content to be served.
+           type: str
+           required: True
+         port:
+           description:
+             - Port number on which the webserver listens for incoming HTTPS connections.
+             - When unspecified, the port is 443.
+           type: int
+         ssl_cert_path:
+           description: Path to the SSL certificate.
+           type: str
+           required: True
+         ssl_key_path:
+           description: Path to the private key corresponding to the SSL certificate.
+           type: str
+           required: True