Update docs (#2)

Author: syndr

README.md

@@ -8,8 +8,35 @@ It provides tooling to create Molecule testing scenarios via the `init` role, an
 
 When utilizing an image with systemd support (systemd packages are installed, etc.), the `docker_platform` role supports the creation of Docker containers with a functional Systemd implementation, which can be used to test Ansible code that makes use of Systemd services or related functionality.
 
+# What is Molecule?
+
+> Molecule project is designed to aid in the development and testing of Ansible roles.
+
+Molecule is a testing platform for your Ansible projects that enables testing of your code both during development and after release via CI infrastructure.
+
+Some resources on Molecule can be found here:
+* [Developing and Testing Ansible Roles with Molecule and Podman - Part 1](https://www.ansible.com/blog/developing-and-testing-ansible-roles-with-molecule-and-podman-part-1)
+* [Testing your Ansible roles with Molecule](https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule)
+* [Ansible Collections: Role Tests with Molecule](https://ericsysmin.com/2020/04/30/ansible-collections-role-tests-with-molecule/)
+* [Introducing Ansible Molecule with Ansible Automation Platform](https://developers.redhat.com/articles/2023/09/13/introducing-ansible-molecule-ansible-automation-platform#an_automation_testing_framework_built_for_the_enterprise)
+
+> [!WARNING]  
+> Some [fairly significant changes](https://ansible.readthedocs.io/projects/molecule/next/) have been made in Molecule v6. Most noticable among these are likely to be that `ansible` is now the only driver included by default (previously called `delegated`), and that the `molecule init` command now only supports creation of scenarios, not Ansible roles. 
+>
+> This [RedHat article](https://developers.redhat.com/articles/2023/09/13/introducing-ansible-molecule-ansible-automation-platform#) has some more information on this change.
+>
+> When reading the above referenced articles, keep in mind their publishing dates, and that there may have been breaking changes to Molecule's functionality since that time!
+
 # Using this collection
 
+The following roles are provided:
+
+* [init](roles/init) - Initialize the Molecule testing framework for a project
+* [docker_platform](roles/docker_platform) - Create a docker-based test platform for Molecule
+* [prepare_controller](roles/prepare_controller) - Prepare a molecule controller to run local code tests
+
+The recommended way to use this collection is to provision Molecule scenarios using the [init role](roles/init). The `init` role provides template configurations that will work in various project types.
+
 ## Host Requirements
 
 The host from which this collection is run (workstation, CI instance, etc.) must meet the following requirements:
@@ -35,7 +62,7 @@ Docker CE can be installed by following the appropriate [installation instructio
 
 ## Project requirements
 
-Roles within this collection will attempt to discover what type of project they are being utilized in. This is enabled by setting the appropriate `project_type` configuration variable to `auto`. The project type can also be explicitly specified if this is desired.
+The `init` role from this collection will attempt to discover what type of project it is being utilized in. This is enabled by setting the `init_project_type` configuration variable to `auto`. The project type can also be explicitly specified if this is desired.
 
 Supported project types:  
 * `role`
@@ -146,17 +173,51 @@ or if your `collections/requirements.yml` includes this collection:
 ansible-galaxy collection install -p ./collections -r ./collections/requirements.yml
 ```
 
-#### Testing roles within a monolithic project
+#### Testing roles and playbooks within a monolithic project
+
+When configuring molecule testing for individual roles or playbooks within a monolithic project (creating a `roles/<role_name>/molecule` or `playbooks/<playbook_name>/molecule` directory), take care _not_ to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created `molecule/default` as described above! Instead, name your role scenario with a unique name.
 
-When configuring molecule testing for individual roles within a monolithic project (creating a `roles/<role_name>/molecule` directory), take care _not_ to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created `molecule/default` as described above! Instead, name your role scenario with a unique name.
+For example (role):
 
 ```bash
 ROLE_NAME=your_role
 mkdir -p molecule/role-$ROLE_NAME
-wget -P molecule/role-$ROLE_NAME https://raw.githubusercontent.com/syndr/ansible-collection-molecule/main/roles/init/files/init.yml
+wget -P molecule/role-$ROLE_NAME https://raw.githubusercontent.com/influxdata/ansible-collection-molecule/main/roles/init/files/init.yml
 ansible-playbook molecule/role-$ROLE_NAME/init.yml
 ```
 
+Note that in this circumstance, you will need to specify the scenario name in order to run molecule against it (as it is not named `default`).
+
+> [!WARNING]  
+> Creating more than one `default` scenario within a repository (IE: within individual roles) will cause Molecule to fail to run at the outer project level!
+
+Running the `molecule list` command will provide you an overview of the available scenarios
+
+```bash
+❯ molecule list                     
+INFO     Running pb-example_playbook > list
+                     ╷             ╷                  ╷                     ╷         ╷            
+  Instance Name      │ Driver Name │ Provisioner Name │ Scenario Name       │ Created │ Converged  
+╶────────────────────┼─────────────┼──────────────────┼─────────────────────┼─────────┼───────────╴
+  docker-rockylinux9 │ default     │ ansible          │ pb-example_playbook │ false   │ false      
+                     ╵             ╵                  ╵                     ╵         ╵
+```
+
+And running the full test suite for this playbook would be done as:
+
+```bash
+molecule test -s pb-example_playbook
+```
+
+While running just the "converge" steps (IE: during development) would be:
+
+```bash
+molecule converge -s pb-example_playbook
+```
+
+> [!TIP]  
+> The `molecule list` command will show multiple scenarios when run in the root of a monolithic project that also has molecule configured on individual playbooks or roles contained within it. Note that you will, however, still need to be in the appropriate role or playbook directory in order to successfully run these scenarios!
+
 # Contributing
 
 Pull requests are welcomed!

roles/init/README.md

@@ -21,7 +21,7 @@ Within the new scenario directory (default), create a file `init.yml` containing
 
 Alternatively, you can run:
 ```bash
-wget -P molecule/default https://raw.githubusercontent.com/syndr/ansible-collection-molecule/main/roles/init/files/init.yml
+wget -P molecule/default https://raw.githubusercontent.com/influxdata/ansible-collection-molecule/main/roles/init/files/init.yml
 ```
 
 Configuration variables for the `init` role launched by this playbook can be customized as desired.