Update AWX collection docs for release 11.0.0

awx_collection/README.md

@@ -3,9 +3,10 @@
 This Ansible collection allows for easy interaction with an AWX or Ansible Tower
 server via Ansible playbooks.
 
-The previous home for this collection was in https://github.com/ansible/ansible
+This source for this collection lives in the `awx_collection` folder inside of the
-inside the folder `lib/ansible/modules/web_infrastructure/ansible_tower`
+AWX source.
-as well as other folders for the inventory plugin, module utils, and
+The previous home for this collection was inside the folder [lib/ansible/modules/web_infrastructure/ansible_tower](https://github.com/ansible/ansible/tree/stable-2.9/lib/ansible/modules/web_infrastructure/ansible_tower) in the Ansible repo,
+as well as other places for the inventory plugin, module utils, and
 doc fragment.
 
 ## Building and Installing
@@ -19,23 +20,42 @@ Installing the `tar.gz` involves no special instructions.
 
 ## Running
 
-Modules in this collection may have any of the following python requirements:
+Non-deprecated modules in this collection have no python requirements, but
+may require the official [AWX CLI](https://docs.ansible.com/ansible-tower/latest/html/towercli/index.html)
+in the future. The `DOCUMENTATION` for each module will report this.
 
- - the official [AWX CLI](https://docs.ansible.com/ansible-tower/latest/html/towercli/index.html)
+You can specify authentication by a combination of either:
- - the deprecated `tower-cli` [PyPI](https://pypi.org/project/ansible-tower-cli/)
+ - host, username, password
- - no requirements
+ - host, OAuth2 token
 
-See requirements in the `DOCUMENTATION` string specific to each module.
+The OAuth2 token is the preferred method. You can obtain a token via the
+AWX CLI [login](https://docs.ansible.com/ansible-tower/latest/html/towercli/reference.html#awx-login)
+command.
+
+These can be specified via:
+ - environment variables (most useful when running against localhost)
+ - direct module parameters
+ - a config file path specified by the `tower_config_file` parameter
+ - a config file at `/etc/tower/tower_cli.cfg`
+ - a config file at `~/.tower_cli.cfg`
+
+Config file syntax looks like this:
+
+```
+[general]
+host = https://localhost:8043
+verify_ssl = true
+oauth_token = LEdCpKVKc4znzffcpQL5vLG8oyeku6
+```
 
 ## Release and Upgrade Notes
 
-The release 7.0.0 of the `awx.awx` collection is intended to be identical
+Notable releases of the `awx.awx` collection:
-to the content prior to the migration, aside from changes necessary to
+ - 7.0.0 is intended to be identical to the content prior to the migration, aside from changes necessary to function as a collection
-have it function as a collection.
+ - 11.0.0 has no non-deprecated modules that depend on the deprecated `tower-cli` [PyPI](https://pypi.org/project/ansible-tower-cli/)
 
 The following notes are changes that may require changes to playbooks:
 
-
  - 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.
  - Specifying a custom certificate via the `TOWER_CERTIFICATE` environment variable no longer works.
@@ -60,7 +80,7 @@ Tests to verify compatibility with the most recent AWX code are in `awx_collecti
 These can be ran by `make test_collection` in the development container.
 
 To run outside of the development container, or to run against
-Ansible or `tower-cli` source, set up a working environment:
+Ansible source, set up a working environment:
 
 ```
 mkvirtualenv my_new_venv
@@ -69,28 +89,17 @@ pip install -r requirements/requirements.txt -r requirements/requirements_dev.tx
 make clean-api
 pip install -e <path to your Ansible>
 pip install -e .
+pip install -e awxkit
 py.test awx_collection/test/awx/
 ```
 
-If you do not install tower-cli, it will skip tests for modules that require it.
-
 ## Running Integration Tests
 
 The integration tests require a virtualenv with `ansible` >= 2.9 and `tower_cli`.
 The collection must first be installed, which can be done using `make install_collection`.
-You also need a configuration file at `~/.tower_cli.cfg` or
+You also need a configuration file, as described in the running section.
-`/etc/tower/tower_cli.cfg` with the credentials for accessing tower. This can
-be populated using `tower-cli`:
 
-```
+Run the tests:
-tower-cli config host $HOST
-tower-cli config username $USERNAME
-tower-cli config password $PASSWORD
-# This tells the tower-cli not to veriffy the ssl certs in the tower, if your tower has good certs you should leave this to true
-tower-cli config verify_ssl false
-```
-
-Finally you can run the tests:
 
 ```
 # ansible-test must be run from the directory in which the collection is installed

awx_collection/plugins/modules/tower_receive.py

@@ -162,7 +162,7 @@ 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")
+    module.deprecate(msg="This module is deprecated and will be replaced by the AWX CLI export command.", version="3.7")
 
     if not HAS_TOWER_CLI:
         module.fail_json(msg='ansible-tower-cli required for this module')

awx_collection/plugins/modules/tower_send.py

@@ -102,7 +102,7 @@ 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")
+    module.deprecate(msg="This module is deprecated and will be replaced by the AWX CLI import command", version="3.7")
 
     if not HAS_TOWER_CLI:
         module.fail_json(msg='ansible-tower-cli required for this module')