Update documentation for modules, add deprecation warning for role, send and receive modules

Update variables in tower_inventory to be in dict format

awx_collection/README.md

@@ -1,7 +1,7 @@
 # AWX Ansible Collection
 
 This Ansible collection allows for easy interaction with an AWX or Ansible Tower
-server in Ansible playbooks.
+server via Ansible playbooks.
 
 The previous home for this collection was in https://github.com/ansible/ansible
 inside the folder `lib/ansible/modules/web_infrastructure/ansible_tower`
@@ -14,34 +14,33 @@ The release 7.0.0 of the `awx.awx` collection is intended to be identical
 to the content prior to the migration, aside from changes necessary to
 have it function as a collection.
 
-The following notes are changes that may require changes to playbooks.
+The following notes are changes that may require changes to playbooks:
 
  - Specifying `inputs` or `injectors` as strings in the
-   `tower_credential_type` module is no longer supported. Provide as dictionaries instead.
+   `tower_credential_type` module is no longer supported. Provide them as dictionaries instead.
  - When a project is created, it will wait for the update/sync to finish by default; this can be turned off with the `wait` parameter, if desired.
  - Creating a "scan" type job template is no longer supported.
  - `extra_vars` in the `tower_job_launch` module worked with a list previously, but is now configured to work solely in a `dict` format.
  - When the `extra_vars` parameter is used with the `tower_job_launch` module, the Job Template launch will fail unless `add_extra_vars` or `survey_enabled` is explicitly set to `True` on the Job Template.
- - tower_group used to also service inventory sources, this functionality has been removed from this module; instead use tower_inventory_source.
+ - `tower_group` used to also service inventory sources, but this functionality has been removed from this module; use `tower_inventory_source` instead.
- - Specified tower_config file used to handle k=v pairs on a single line. This is no longer supported. You may a file formatted in: yaml, json or ini only.
+ - Specified `tower_config` file used to handle `k=v` pairs on a single line; this is no longer supported. Please use a file formatted as `yaml`, `json` or `ini` only.
- - The `variables` parameter in the `tower_group` and `tower_host` modules are now in `dict` format and no longer
+ - The `variables` parameter in the `tower_group`, `tower_host` and `tower_inventory` modules are now in `dict` format and no longer supports the use of the `C(@)` syntax (for an external `vars` file).
- supports the use of the `C(@)` syntax (for an external vars file).
+ - Some return values (e.g., `credential_type`) have been removed. Use of `id` is recommended.
 
 ## Running
 
-To use this collection, the "old" tower-cli needs to be installed
+To use this collection, the "old" `tower-cli` needs to be installed
 in the virtual environment where the collection runs.
 You can install it from [PyPI](https://pypi.org/project/ansible-tower-cli/).
 
-To use this collection in AWX, you should create a custom virtual environment
+To use this collection in AWX, you should create a custom virtual environment into which to install the requirements. NOTE: running locally, you will also need
-to install the requirement into. NOTE: running locally, you will also need
+to set the job template `extra_vars` to include `ansible_python_interpreter`
-to set the job template extra_vars to include `ansible_python_interpreter`
+to be the Python in that virtual environment.
-to be the python in that virtual environment.
 
 ## Running Tests
 
 Tests to verify compatibility with the most recent AWX code are
-in `awx_collection/test/awx`. These tests require that python packages
+in `awx_collection/test/awx`. These tests require that Python packages
 are available for all of `awx`, `ansible`, `tower_cli`, and the collection
 itself.
 
@@ -49,7 +48,7 @@ itself.
 
 The target `make prepare_collection_venv` will prepare some requirements
 in the `awx_collection_test_venv` folder so that `make test_collection` can
-be ran to actually run the tests. A single test can be ran via:
+be executed to actually run the tests. A single test can be run via:
 
 ```
 make test_collection COLLECTION_TEST_DIRS=awx_collection/test/awx/test_organization.py
@@ -57,9 +56,9 @@ make test_collection COLLECTION_TEST_DIRS=awx_collection/test/awx/test_organizat
 
 ### Manually
 
-As a faster alternative if you do not want to use the container, or
+As a faster alternative (if you do not want to use the container), or to
-run against Ansible or tower-cli source, it is possible to set up a
+run against Ansible or `tower-cli` source, it is possible to set up a
-working environment yourself.
+working environment yourself:
 
 ```
 mkvirtualenv my_new_venv

awx_collection/plugins/modules/tower_credential_type.py

@@ -69,6 +69,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_group.py

@@ -33,6 +33,7 @@ options:
         - A new name for this group (for renaming)
       required: False
       type: str
+      version_added: "3.7"
     description:
       description:
         - The description to use for the group.
@@ -57,6 +58,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -80,7 +82,7 @@ def main():
     argument_spec = dict(
         name=dict(required=True),
         new_name=dict(required=False),
-        description=dict(),
+        description=dict(required=False),
         inventory=dict(required=True),
         variables=dict(type='dict', required=False),
         state=dict(choices=['present', 'absent'], default='present'),

awx_collection/plugins/modules/tower_host.py

@@ -33,6 +33,7 @@ options:
         - To use when changing a hosts's name.
       required: False
       type: str
+      version_added: "3.7"
     description:
       description:
         - The description to use for the host.
@@ -62,6 +63,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -88,7 +90,7 @@ def main():
     argument_spec = dict(
         name=dict(required=True),
         new_name=dict(required=False),
-        description=dict(default=''),
+        description=dict(required=False),
         inventory=dict(required=True),
         enabled=dict(type='bool', default=True),
         variables=dict(type='dict', required=False),

awx_collection/plugins/modules/tower_inventory.py

@@ -39,8 +39,9 @@ options:
       type: str
     variables:
       description:
-        - Inventory variables. Use C(@) to get from file.
+        - Inventory variables.
-      type: str
+      required: False
+      type: dict
     kind:
       description:
         - The kind field. Cannot be modified after created.
@@ -64,6 +65,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -86,9 +88,9 @@ def main():
     # Any additional arguments that are not fields of the item can be added here
     argument_spec = dict(
         name=dict(required=True),
-        description=dict(default=''),
+        description=dict(required=False),
         organization=dict(required=True),
-        variables=dict(default=''),
+        variables=dict(type='dict', required=False),
         kind=dict(choices=['', 'smart'], default=''),
         host_filter=dict(),
         state=dict(choices=['present', 'absent'], default='present'),

awx_collection/plugins/modules/tower_inventory_source.py

@@ -33,6 +33,7 @@ options:
         - A new name for this assets (will rename the asset)
       required: False
       type: str
+      version_added: "3.7"
     description:
       description:
         - The description to use for the inventory source.
@@ -127,6 +128,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -152,7 +154,7 @@ def main():
     argument_spec = dict(
         name=dict(required=True),
         new_name=dict(type='str'),
-        description=dict(),
+        description=dict(required=False),
         inventory=dict(required=True),
         #
         # How do we handle manual and file? Tower does not seem to be able to activate them

awx_collection/plugins/modules/tower_job_cancel.py

@@ -38,6 +38,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_job_launch.py

@@ -64,29 +64,35 @@ options:
         - A specific of the SCM project to run the template on.
         - This is only applicable if your project allows for branch override.
       type: str
+      version_added: "3.7"
     skip_tags:
       description:
         - Specific tags to skip from the playbook.
       type: list
       elements: str
+      version_added: "3.7"
     verbosity:
       description:
         - Verbosity level for this job run
       type: int
       choices: [ 0, 1, 2, 3, 4, 5 ]
+      version_added: "3.7"
     diff_mode:
       description:
         - Show the changes made by Ansible tasks where supported
       type: bool
+      version_added: "3.7"
     credential_passwords:
       description:
         - Passwords for credentials which are set to prompt on launch
       type: dict
+      version_added: "3.7"
     tower_oauthtoken:
       description:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_job_list.py

@@ -46,6 +46,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_license.py

@@ -27,16 +27,19 @@ options:
         - The contents of the license file
       required: True
       type: dict
+      version_added: "3.7"
     eula_accepted:
       description:
         - Whether or not the EULA is accepted.
       required: True
       type: bool
+      version_added: "3.7"
     tower_oauthtoken:
       description:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_organization.py

@@ -45,6 +45,7 @@ options:
       default: "0"
       type: int
       required: False
+      version_added: "3.7"
     state:
       description:
         - Desired state of the resource.
@@ -56,6 +57,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_project.py

@@ -56,6 +56,7 @@ options:
         - The refspec to use for the SCM resource.
       type: str
       default: ''
+      version_added: "3.7"
     scm_credential:
       description:
         - Name of the credential to use with this SCM resource.
@@ -86,6 +87,7 @@ options:
       description:
         - Allow changing the SCM branch or revision in a job template that uses this project.
       type: bool
+      version_added: "3.7"
     job_timeout:
       version_added: "2.8"
       description:
@@ -123,6 +125,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -175,7 +178,7 @@ def main():
     # Any additional arguments that are not fields of the item can be added here
     argument_spec = dict(
         name=dict(required=True),
-        description=dict(required=False, default=''),
+        description=dict(required=False),
         scm_type=dict(required=False, choices=['manual', 'git', 'hg', 'svn', 'insights'], default='manual'),
         scm_url=dict(required=False),
         local_path=dict(required=False),

awx_collection/plugins/modules/tower_receive.py

@@ -162,6 +162,8 @@ def main():
 
     module = TowerModule(argument_spec=argument_spec, supports_check_mode=False)
 
+    module.deprecate(msg="This module is being moved to a different collection. Instead of awx.awx it will be migrated into awx.tower_cli", version="3.7")
+
     if not HAS_TOWER_CLI:
         module.fail_json(msg='ansible-tower-cli required for this module')
 

awx_collection/plugins/modules/tower_role.py

@@ -141,6 +141,8 @@ def main():
 
     module = TowerModule(argument_spec=argument_spec, supports_check_mode=True)
 
+    module.deprecate(msg="This module is being moved to a different collection. Instead of awx.awx it will be migrated into awx.tower_cli", version="3.7")
+
     role_type = module.params.pop('role')
     state = module.params.pop('state')
 

awx_collection/plugins/modules/tower_send.py

@@ -106,6 +106,8 @@ def main():
 
     module = TowerModule(argument_spec=argument_spec, supports_check_mode=False)
 
+    module.deprecate(msg="This module is being moved to a different collection. Instead of awx.awx it will be migrated into awx.tower_cli", version="3.7")
+
     if not HAS_TOWER_CLI:
         module.fail_json(msg='ansible-tower-cli required for this module')
 

awx_collection/plugins/modules/tower_settings.py

@@ -38,11 +38,13 @@ options:
         - A data structure to be sent into the settings endpoint
       required: False
       type: dict
+      version_added: "3.7"
     tower_oauthtoken:
       description:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 

awx_collection/plugins/modules/tower_team.py

@@ -33,9 +33,11 @@ options:
         - To use when changing a team's name.
       required: False
       type: str
+      version_added: "3.7"
     description:
       description:
         - The description to use for the team.
+      required: False
       type: str
     organization:
       description:
@@ -53,6 +55,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''
 
@@ -75,7 +78,7 @@ def main():
     argument_spec = dict(
         name=dict(required=True),
         new_name=dict(required=False),
-        description=dict(),
+        description=dict(required=False),
         organization=dict(required=True),
         state=dict(choices=['present', 'absent'], default='present'),
     )

awx_collection/plugins/modules/tower_user.py

@@ -66,6 +66,7 @@ options:
         - The Tower OAuth token to use.
       required: False
       type: str
+      version_added: "3.7"
 extends_documentation_fragment: awx.awx.auth
 '''