Add playbook argspec to init project scaffolding and as resource (#420)

* Add playbook argspec to init project scaffolding and as resource

* Fixing file extension and adding test

* Removing .j2 extension from files

* Updating argspec definition and playbook as needed

* Whoops, forgot to update test fixtures

* Updating playbook and argspec files with additional metadata

* Correcting filenames

* Add more detail to playbook header comments

Author: alisonlhart

docs/installing.md

@@ -390,12 +390,13 @@ $ ansible-creator add resource <resource-type> <path>
 
 #### Positional Arguments
 
-| Parameter             | Description                                                      |
-| --------------------- | ---------------------------------------------------------------- |
-| devcontainer          | Add devcontainer files to an existing Ansible project.           |
-| devfile               | Add a devfile file to an existing Ansible project.               |
-| role                  | Add a role to an existing Ansible collection.                    |
-| execution-environment | Add a sample execution-environment.yml file to an existing path. |
+| Parameter             | Description                                                        |
+| --------------------- | ------------------------------------------------------------------ |
+| devcontainer          | Add devcontainer files to an existing Ansible project.             |
+| devfile               | Add a devfile file to an existing Ansible project.                 |
+| play-argspec          | Add playbook argspec examples file to an existing Ansible project. |
+| role                  | Add a role to an existing Ansible collection.                      |
+| execution-environment | Add a sample execution-environment.yml file to an existing path.   |
 
 #### Example of adding a resource
 

src/ansible_creator/arg_parser.py

@@ -211,6 +211,7 @@ def _add_resource(self, subparser: SubParser[ArgumentParser]) -> None:
         )
         self._add_resource_devcontainer(subparser=subparser)
         self._add_resource_devfile(subparser=subparser)
+        self._add_resource_play_argspec(subparser=subparser)
         self._add_resource_role(subparser=subparser)
         self._add_resource_execution_env(subparser=subparser)
 
@@ -268,6 +269,29 @@ def _add_resource_devfile(self, subparser: SubParser[ArgumentParser]) -> None:
         self._add_overwrite(parser)
         self._add_args_common(parser)
 
+    def _add_resource_play_argspec(self, subparser: SubParser[ArgumentParser]) -> None:
+        """Add example playbook argspec files to an existing Ansible project.
+
+        Args:
+            subparser: The subparser to add playbook argspec files to
+        """
+        parser = subparser.add_parser(
+            "play-argspec",
+            help="Add example playbook argspec files to an existing Ansible project.",
+            formatter_class=CustomHelpFormatter,
+        )
+
+        parser.add_argument(
+            "path",
+            default="./",
+            metavar="path",
+            help="The destination directory for the playbook argspec files. The default is the "
+            "current working directory.",
+        )
+
+        self._add_overwrite(parser)
+        self._add_args_common(parser)
+
     def _add_resource_role(self, subparser: SubParser[ArgumentParser]) -> None:
         """Add a role to an existing Ansible collection.
 

src/ansible_creator/resources/common/play-argspec/argspec_validation_plays.meta.yml

@@ -0,0 +1,61 @@
+# Example play argspec file
+---
+short_description: A shorter summary of `description` below
+description: This is a description of a playbook, that may contain multiple plays with multiple play argument specs
+argument_specs:
+  debug_localhost:
+    short_description: Play for printing a debug message
+    description:
+      - Example play within a collection containing an argspec for printing a debug message
+    author:
+      - developer (@developer)
+    options:
+      message:
+        description: Debug message to print
+        type: str
+        required: true
+    examples: |
+      - import_playbook: argspec_validation_plays.yml
+        vars:
+          message: 'Custom debug message'
+    return: ~
+  ping_localhost:
+    short_description: Play for pinging localhost with custom data
+    description:
+      - Example play within a collection containing an argspec for pinging localhost with custom data
+    author:
+      - developer (@developer)
+    options:
+      ping_data:
+        description: Ping data
+        type: str
+        required: true
+    examples: |
+      - import_playbook: argspec_validation_plays.yml
+        vars:
+          data: Pong
+    return: ~
+  set_stats:
+    short_description: Play for setting a custom stat
+    description:
+      - Example play within a collection containing an argspec for setting a custom stat
+    author:
+      - developer (@developer)
+    options:
+      stat:
+        description: Stat data
+        type: raw
+        required: true
+    notes:
+      - This play has some notes
+      - They specify additional information
+    examples: |
+      - import_playbook: argspec_validation_plays.yml
+        vars:
+          stat: This is some custom stat
+    return:
+      stat:
+        description: Custom stat data
+        returned: always
+        type: raw
+        sample: Hello, World!

src/ansible_creator/resources/common/play-argspec/argspec_validation_plays.yml

@@ -0,0 +1,45 @@
+# Example playbook using play argspec validation
+# Run with:
+# ansible-playbook argspec_validation_plays.yml -e message=hello -i inventory/argspec_validation_inventory.yml
+---
+- name: Debug_localhost
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify with argspec
+      ansible.builtin.validate_argument_spec:
+        argument_spec: "{{ (lookup('ansible.builtin.file', filename) | from_yaml)['argument_specs'][lowercase_play_name]['options'] }}"
+      vars:
+        lowercase_play_name: "{{ ansible_play_name | lower }}"
+        filename: "argspec_validation_plays.meta.yml"
+    - name: Print debug message
+      ansible.builtin.debug:
+        msg: "{{ message }}"
+
+- name: Ping_localhost
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify with argspec
+      ansible.builtin.validate_argument_spec:
+        argument_spec: "{{ (lookup('ansible.builtin.file', filename) | from_yaml)['argument_specs'][lowercase_play_name]['options'] }}"
+      vars:
+        lowercase_play_name: "{{ ansible_play_name | lower }}"
+        filename: "argspec_validation_plays.meta.yml"
+    - name: Print debug message
+      ansible.builtin.ping:
+        data: "{{ ping_data }}"
+
+- name: Set_stats
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify with argspec
+      ansible.builtin.validate_argument_spec:
+        argument_spec: "{{ (lookup('ansible.builtin.file', filename) | from_yaml)['argument_specs'][lowercase_play_name]['options'] }}"
+      vars:
+        lowercase_play_name: "{{ ansible_play_name | lower }}"
+        filename: "argspec_validation_plays.meta.yml"
+    - name: Set custom stats
+      ansible.builtin.set_stats:
+        data: "{{ stat }}"

src/ansible_creator/resources/common/play-argspec/inventory/argspec_validation_inventory.yml

@@ -0,0 +1,9 @@
+---
+all:
+  vars:
+    ping_data: Pong
+    stat:
+      description: Custom stat data
+      returned: always
+      type: raw
+      sample: Hello, World!

src/ansible_creator/resources/playbook_project/README.md.j2

@@ -30,9 +30,10 @@ project requirements.
  |                         └── README.md
  |                         └── tasks/main.yml
  |── inventory/
+ |   |── hosts.yml
+ |   |── argspec_validation_inventory.yml
  |   └── groups_vars/
  |   └── host_vars/
- |   └── hosts.yml
  |── ansible-navigator.yml
  |── ansible.cfg
  |── devfile.yaml

src/ansible_creator/resources/playbook_project/argspec_validation_plays.meta.yml

@@ -0,0 +1,61 @@
+# Example play argspec file
+---
+short_description: A shorter summary of `description` below
+description: This is a description of a playbook, that may contain multiple plays with multiple play argument specs
+argument_specs:
+  debug_localhost:
+    short_description: Play for printing a debug message
+    description:
+      - Example play within a collection containing an argspec for printing a debug message
+    author:
+      - developer (@developer)
+    options:
+      message:
+        description: Debug message to print
+        type: str
+        required: true
+    examples: |
+      - import_playbook: argspec_validation_plays.yml
+        vars:
+          message: 'Custom debug message'
+    return: ~
+  ping_localhost:
+    short_description: Play for pinging localhost with custom data
+    description:
+      - Example play within a collection containing an argspec for pinging localhost with custom data
+    author:
+      - developer (@developer)
+    options:
+      ping_data:
+        description: Ping data
+        type: str
+        required: true
+    examples: |
+      - import_playbook: argspec_validation_plays.yml
+        vars:
+          data: Pong
+    return: ~
+  set_stats:
+    short_description: Play for setting a custom stat
+    description:
+      - Example play within a collection containing an argspec for setting a custom stat
+    author:
+      - developer (@developer)
+    options:
+      stat:
+        description: Stat data
+        type: raw
+        required: true
+    notes:
+      - This play has some notes
+      - They specify additional information
+    examples: |
+      - import_playbook: argspec_validation_plays.yml
+        vars:
+          stat: This is some custom stat
+    return:
+      stat:
+        description: Custom stat data
+        returned: always
+        type: raw
+        sample: Hello, World!

src/ansible_creator/resources/playbook_project/argspec_validation_plays.yml

@@ -0,0 +1,45 @@
+# Example playbook using play argspec validation
+# Run with:
+# ansible-playbook argspec_validation_plays.yml -e message=hello -i inventory/argspec_validation_inventory.yml
+---
+- name: Debug_localhost
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify with argspec
+      ansible.builtin.validate_argument_spec:
+        argument_spec: "{{ (lookup('ansible.builtin.file', filename) | from_yaml)['argument_specs'][lowercase_play_name]['options'] }}"
+      vars:
+        lowercase_play_name: "{{ ansible_play_name | lower }}"
+        filename: "argspec_validation_plays.meta.yml"
+    - name: Print debug message
+      ansible.builtin.debug:
+        msg: "{{ message }}"
+
+- name: Ping_localhost
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify with argspec
+      ansible.builtin.validate_argument_spec:
+        argument_spec: "{{ (lookup('ansible.builtin.file', filename) | from_yaml)['argument_specs'][lowercase_play_name]['options'] }}"
+      vars:
+        lowercase_play_name: "{{ ansible_play_name | lower }}"
+        filename: "argspec_validation_plays.meta.yml"
+    - name: Print debug message
+      ansible.builtin.ping:
+        data: "{{ ping_data }}"
+
+- name: Set_stats
+  hosts: localhost
+  gather_facts: false
+  tasks:
+    - name: Verify with argspec
+      ansible.builtin.validate_argument_spec:
+        argument_spec: "{{ (lookup('ansible.builtin.file', filename) | from_yaml)['argument_specs'][lowercase_play_name]['options'] }}"
+      vars:
+        lowercase_play_name: "{{ ansible_play_name | lower }}"
+        filename: "argspec_validation_plays.meta.yml"
+    - name: Set custom stats
+      ansible.builtin.set_stats:
+        data: "{{ stat }}"

src/ansible_creator/resources/playbook_project/inventory/argspec_validation_inventory.yml

@@ -0,0 +1,9 @@
+---
+all:
+  vars:
+    ping_data: Pong
+    stat:
+      description: Custom stat data
+      returned: always
+      type: raw
+      sample: Hello, World!

src/ansible_creator/subcommands/add.py

@@ -163,6 +163,8 @@ def _resource_scaffold(self) -> None:
             template_data = self._get_devcontainer_template_data()
         elif self._resource_type == "execution-environment":
             template_data = self._get_ee_template_data()
+        elif self._resource_type == "play-argspec":
+            template_data = self._get_play_argspec_template_data()
         elif self._resource_type == "role":
             self._check_collection_path()
             self._namespace, self._collection_name = self.role_galaxy()
@@ -414,10 +416,21 @@ def _get_plugin_template_data(self) -> TemplateData:
         )
 
     def _get_ee_template_data(self) -> TemplateData:
-        """Get the template data for plugin.
+        """Get the template data for ee resources.
 
         Returns:
-            TemplateData: Data required for templating the plugin.
+            TemplateData: Data required for templating the ee resources.
+        """
+        return TemplateData(
+            resource_type=self._resource_type,
+            creator_version=self._creator_version,
+        )
+
+    def _get_play_argspec_template_data(self) -> TemplateData:
+        """Get the template data for playbook argspec resources.
+
+        Returns:
+            TemplateData: Data required for templating the playbook argspec resources.
         """
         return TemplateData(
             resource_type=self._resource_type,

tests/fixtures/project/playbook_project/README.md

@@ -30,9 +30,10 @@ project requirements.
  |                         └── README.md
  |                         └── tasks/main.yml
  |── inventory/
+ |   |── hosts.yml
+ |   |── argspec_validation_inventory.yml
  |   └── groups_vars/
  |   └── host_vars/
- |   └── hosts.yml
  |── ansible-navigator.yml
  |── ansible.cfg
  |── devfile.yaml