Merge pull request #11 from UpCloudLtd/chore/update-readme [ci skip]

Improve README.md in many ways

README.md

@@ -14,38 +14,56 @@ If you find yourself needing a specific service as an inventory, please open an
 [issue](https://github.com/UpCloudLtd/upcloud-ansible-collection/issues). Please see the development & contribution
 sections below for development quickstart if you're interested in adding new features or making fixes.
 
-## Requirements
+## Getting Started
 
-UpCloud Collection requires [UpCloud API's Python bindings](https://pypi.org/project/upcloud-api/) to be installed
-in order to work. It can be installed from the Python Package Index with the `pip` tool. The collection
-itself can be installed with the `ansible-galaxy` command that comes in the Ansible package.
+### Prerequisites
+
+UpCloud Collection requires [UpCloud API's Python bindings](https://pypi.org/project/upcloud-api/) version 2.0.0 or
+newer in order to work. It can be installed from the Python Package Index with the `pip` tool:
+
+```bash
+pip3 install upcloud-api>=2.0.0
+```
+
+The collection itself can be installed with the `ansible-galaxy` command that comes with the Ansible package:
 
 ```bash
-pip3 install upcloud-api
 ansible-galaxy collection install https://github.com/UpCloudLtd/upcloud-ansible-collection/releases/download/v0.5.0/community-upcloud-0.5.0.tar.gz
 ```
 
-## Inventory usage
+### Inventory usage
+
+Inventory file must be named so that it ends either in `upcloud.yml` or `upcloud.yaml`. It is also possible to filter
+servers based on their zone, tags, state, or the network they belong to.
 
-As UpCloud Collection is not part of the official Ansible release and Ansible itself still has some figuring out
-to do with collections, a few extra files are needed for your playbook to function. Following configuration
-options should be either in your existing config, or if you're using defaults, just have these in `ansible.cfg`
-in your playbook's root folder.
+#### Quick Start
 
+Create an `upcloud.yml` file with these contents:
+
+```yaml
+plugin: community.upcloud.upcloud
 ```
-[default]
-collections_paths = ~/.ansible/collections:/usr/share/ansible/collections
 
-[inventory]
-enable_plugins = community.upcloud.upcloud
+Set environment variables for API authentication:
+
+```bash
+export UPCLOUD_USERNAME="upcloud-api-access-enabled-user"
+export UPCLOUD_PASSWORD="verysecretpassword"
 ```
 
-Inventory file must be named so that it ends either in `upcloud.yml` or `upcloud.yaml`. If you want to include
-all your servers in the inventory, inventory file can just have `plugin: community.upcloud.upcloud` as its content.
-It is also possible to filter servers based on their zone, tags, state, or the network they belong to.
-Following example has all the possibilities, but you can choose what to filter on:
+And show the Ansible inventory information as a graph:
 
+```bash
+ansible-inventory -i upcloud.yml --graph
 ```
+
+You should see a list of hosts.
+
+#### Further examples
+
+You can filter based on multiple data points:
+
+```yaml
 plugin: community.upcloud.upcloud
 zones:
   - fi-hel2
@@ -59,7 +77,7 @@ network: 035a0a8a-7704-4da5-820d-129fc8232714
 
 Servers can also be grouped by status, zone etc by specifying them as `keyed_groups`.
 
-```
+```yaml
 plugin: community.upcloud.upcloud
 keyed_groups:
   - key: zone
@@ -71,12 +89,28 @@ keyed_groups:
 Examples here assume that API credentials are available as environment variables
 (`UPCLOUD_USERNAME` & `UPCLOUD_PASSWORD`). They can also be defined in inventory file:
 
-```
+```yaml
 plugin: community.upcloud.upcloud
 username: YOUR_USERNAME
 password: YOUR_PASSWORD
 ```
 
+## Troubleshooting
+
+If you are having problems loading, finding or enabling the collection, you might need to create or modify your
+existing `ansible.cfg`config. Adding the following settings should ensure that the collection can be found and is
+enabled:
+
+```
+[default]
+collections_paths = ~/.ansible/collections:/usr/share/ansible/collections
+
+[inventory]
+enable_plugins = community.upcloud.upcloud
+```
+
+Note that, if you are using any other plugins, those should be listed in `enable_plugins` as well.
+
 ## Changelog
 
 Changelog is available [in its own file](CHANGELOG.md).