Prepare documentation for the 1.0 release

We added or modified all of the vital parts of the documentation in
preparation for the 1.0 release. Note that since documentation is not
hosted on Ansible Galaxy or Automation Hub, we can easily improve it
even after the release as long as we do not remove existing sections
and break the documents that link to our docs.

Co-Authored-By: mancabizjak <[email protected]>

README.md

@@ -1,70 +1,19 @@
 # Sensu Go Ansible Collection
 
-Sensu Go [Ansible Collection][collection] contains:
+Sensu Go Ansible Collection is a bundle of Ansible content that we can use to
+manage all aspects of Sensu Go. It contains Ansible roles for installing and
+configuring backends and agents. Collection also contains a wide selection of
+modules for runtime management of Sensu Go backend.
 
-* Ansible roles to install [Sensu Go][sensu] on your nodes.
-* Ansible modules for interacting with [Sensu Go][sensu] REST API.
+Collection is freely available on [Ansible Galaxy][galaxy]. For Red Hat
+subscribers, this collection is also available on [Automation Hub][hub].
 
-   [collection]: https://docs.ansible.com/ansible/latest/user_guide/collections_using.html
-                 (Using Ansible Collections)
-   [sensu]: https://docs.sensu.io/sensu-go/latest
-            (Sensu Go documentation)
+   [galaxy]: https://galaxy.ansible.com/sensu/sensu_go
+             (Sensu Go on Ansible Galaxy)
+   [hub]: https://cloud.redhat.com/ansible/automation-hub/sensu/sensu_go
+          (Sensu Go on Automation Hub)
 
+For user guides and references, please visit [the documentation site][docs].
 
-## Installation
-
-If we would like to install the Sensu Go collection, we need to have Ansible
-2.9 or later installed. Once we have taken care of this, we can install the
-Sensu Go collection from [Ansible Galaxy][galaxy] by running:
-
-    $ ansible-galaxy collection install sensu.sensu_go
-
-   [galaxy]: https://galaxy.ansible.com (Ansible Galaxy)
-
-
-## Usage
-
-We can use the namespaced modules and roles:
-
-    - hosts: localhost
-      roles:
-        - sensu.sensu_go.backend
-      tasks:
-        - name: List Assets
-          sensu.sensu_go.asset_info:
-          register: assets
-
-        - name: List Filters
-          sensu.sensu_go.filter_info:
-          register: filters
-
-Or use the `collections` keyword to create the search path, then use bare
-names:
-
-    - hosts: localhost
-      collections: [sensu.sensu_go]
-      roles:
-        - backend
-      tasks:
-        - name: List Assets
-          asset_info:
-          register: assets
-
-        - name: List Filters
-          filter_info:
-          register: filters
-
-
-## Support
-
-Sensu will offer support for the contents of the collection. Details about the
-support will be made available as soon as the collection is certified.
-
-
-## Acknowledgement
-
-We would like to thank [@flowerysong][flowerysong] for initial implementation
-of the Ansible modules provided in this collection.
-
-   [flowerysong]: https://github.com/flowerysong/ansible-sensu-go
-                 (@flowerysong's GitHub profile)
+   [docs]: https://sensu.github.io/sensu-go-ansible/
+           (Sensu Go Ansible Collection documentation)

docs/examples/installation/ansible.cfg

@@ -0,0 +1,10 @@
+[galaxy]
+server_list = automation_hub, galaxy
+
+[galaxy_server.automation_hub]
+url=https://cloud.redhat.com/api/automation-hub/
+auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
+token=AABBccddeeff112233gghh...
+
+[galaxy_server.galaxy]
+url=https://galaxy.ansible.com/

docs/examples/quickstart/inventory.yaml

@@ -0,0 +1,9 @@
+all:
+  children:
+    backends:
+      hosts:
+        192.168.50.4:
+
+    agents:
+      hosts:
+        192.168.50.5:

docs/examples/quickstart/playbook.yaml

@@ -0,0 +1,50 @@
+---
+- name: Install, configure and run Sensu backend
+  hosts: backends
+  become: true
+
+  tasks:
+    - name: Install backend
+      include_role:
+        name: sensu.sensu_go.backend
+
+- name: Install, configure and run Sensu agents
+  hosts: agents
+  become: true
+
+  tasks:
+    - name: Install agent
+      include_role:
+        name: sensu.sensu_go.agent
+      vars:
+        agent_config:
+          deregister: true
+          keepalive-interval: 5
+          keepalive-timeout: 10
+          subscriptions:
+            - linux
+
+- name: Configure your first monitor
+  hosts: localhost
+  collections:
+    - sensu.sensu_go
+  tasks:
+    - name: Create sensu asset
+      bonsai_asset:
+        auth: &auth
+          url: http://{{ groups['backends'][0] }}:8080
+        name: sensu/monitoring-plugins
+        version: 2.2.0-1
+
+    - name: Create sensu ntp check
+      check:
+        auth: *auth
+        name: ntp
+        runtime_assets: sensu/monitoring-plugins
+        command: check_ntp_time -H time.nist.gov --warn 0.5 --critical 1.0
+        output_metric_format: nagios_perfdata
+        publish: true 
+        interval: 30
+        timeout: 10
+        subscriptions: 
+          - linux

docs/examples/roles/agent.yaml

@@ -0,0 +1,8 @@
+---
+- name: Install, configure and run Sensu agent
+  hosts: agents
+  roles:
+    - sensu.sensu_go.agent
+  vars:
+    agent_config:
+      backend-url: [ ws://upstream-backend:4321 ]

docs/examples/roles/backend.yaml

@@ -0,0 +1,7 @@
+- name: Install, configure and run Sensu backend
+  hosts: backends
+  roles:
+    - sensu.sensu_go.backend
+  vars:
+    backend_config:
+      log-level: debug

docs/examples/roles/install.yaml

@@ -0,0 +1,22 @@
+---
+- name: Install sensu-backend binary
+  hosts: backends
+  roles:
+     - sensu.sensu_go.install
+  vars:
+    components: [ sensu-go-backend ]
+
+- name: Install sensu-agent binary from testing repository
+  hosts: agents
+  roles:
+     - sensu.sensu_go.install
+  vars:
+    components: [ sensu-go-agent ]
+    channel: testing
+
+- name: Install sensuctl binary
+  hosts: localhost
+  roles:
+     - sensu.sensu_go.install
+  vars:
+    components: [ sensu-go-cli ]

docs/source/index.rst

@@ -1,81 +1,36 @@
 Sensu Go Ansible Collection
 ===========================
 
-Sensu Go `Ansible Collection`_ contains:
+Sensu Go Ansible Collection is a bundle of Ansible content that we can use to
+manage all aspects of Sensu Go. It contains Ansible roles for installing and
+configuring backends and agents. Collection also contains a wide selection of
+modules for runtime management of Sensu Go backend.
 
-* Ansible roles to install `Sensu Go`_ on your nodes.
-* Ansible modules for interacting with `Sensu Go`_ REST API.
+Collection is freely available on `Ansible Galaxy`_. For Red Hat subscribers,
+this collection is also available on `Automation Hub`_.
 
-.. _Ansible Collection:
-   https://docs.ansible.com/ansible/latest/user_guide/collections_using.html
-.. _Sensu Go: https://docs.sensu.io/sensu-go/latest
+.. _Ansible Galaxy:
+   https://galaxy.ansible.com/sensu/sensu_go
+.. _Automation Hub:
+   https://cloud.redhat.com/ansible/automation-hub/sensu/sensu_go
 
 
-Installation
-------------
-
-If we would like to install the Sensu Go collection, we need to have Ansible
-2.9 or later installed. Once we have taken care of this, we can install the
-Sensu Go collection from `Ansible Galaxy`_ by running::
-
-   $ ansible-galaxy collection install sensu.sensu_go
-
-.. _Ansible Galaxy: https://galaxy.ansible.com
-
-
-Usage
------
-
-We can use the namespaced modules::
-
-   - hosts: localhost
-     roles:
-       - sensu.sensu_go.backend
-     tasks:
-       - name: List Assets
-         sensu.sensu_go.asset_info:
-         register: assets
-
-       - name: List Filters
-         sensu.sensu_go.filter_info:
-         register: filters
-
-Or use the `collections` keyword to create the search path, then use bare
-names::
-
-   - hosts: localhost
-     collections: [sensu.sensu_go]
-     roles:
-       - backend
-     tasks:
-       - name: List Assets
-         asset_info:
-         register: assets
-
-       - name: List Filters
-         filter_info:
-         register: filters
-
-
-Support
--------
-
-Sensu will offer support for the contents of the collection. Details about the
-support will be made available as soon as the collection is certified.
-
-
-Acknowledgement
----------------
+.. toctree::
+   :maxdepth: 2
+   :caption: Using Sensu Go Ansible Collection
 
-We would like to thank `@flowerysong`_ for initial implementation of the
-Ansible modules provided in this collection.
+   quickstart
+   installation
 
-.. _@flowerysong: https://github.com/flowerysong/ansible-sensu-go
+.. toctree::
+   :maxdepth: 1
+   :caption: References
 
+   roles
+   modules
 
 .. toctree::
    :maxdepth: 1
-   :hidden:
+   :caption: Appendices
 
-   sandbox
-   module_index
+   release_notes

docs/source/installation.rst

@@ -0,0 +1,80 @@
+Installation
+============
+
+We can install Sensu Go Ansible collection using the ``ansible-galaxy`` tool
+that comes bundled with Ansible. This tool can install Ansible collections
+from different sources.
+
+
+Installing from Ansible Galaxy
+------------------------------
+
+`Ansible Galaxy`_ is the default source of Ansible collections for the
+``ansible-galaxy`` tool. We can install Sensu Go Ansible collection by
+running::
+
+   $ ansible-galaxy collection install sensu.sensu_go
+
+.. _Ansible Galaxy: https://galaxy.ansible.com
+
+After the command finishes, we will have the latest version of the Sensu Go
+Ansible collection installed and ready to be used.
+
+We can also install a specific version of the collection by appending a
+version after the name::
+
+   $ ansible-galaxy collection install sensu.sensu_go:1.0.0
+
+.. note::
+
+   ``ansible-galaxy`` command will not overwrite the existing collection if it
+   is already installed. We can change this default behavior by adding a
+   ``--force`` command line switch::
+
+      $ ansible-galaxy collection install --force sensu.sensu_go:1.0.0
+
+The official Ansible documentation contains more information about the
+installation options in the `Using collections`_ document.
+
+.. _Using collections:
+   https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#installing-collections
+
+
+Installing from Automation Hub
+------------------------------
+
+If we have a valid Red Hat subscription, we can also install Sensu Go Ansible
+collection from Red Hat Ansible Automation Hub. But before we can do that, we
+need to tell Ansible about the second source of collections. We do this by
+placing the following content into the
+:download:`ansible.cfg <../examples/installation/ansible.cfg>` configuration
+file:
+
+.. literalinclude:: ../examples/installation/ansible.cfg
+   :language: ini
+
+
+Make sure you replace the ``token`` value in the above configuration with the
+value obtained from the `token Automation Hub UI`_.
+
+.. _token Automation Hub UI:
+   https://cloud.redhat.com/ansible/automation-hub/token
+
+From here on, we can follow the steps from the previous section.
+
+
+Installing from a local file
+----------------------------
+
+This last method of installation might come in handy in situations where our
+Ansible control node cannot access Ansible Galaxy or Automation Hub.
+
+First, we need to download the Sensu Go Ansible collection archive from the
+GitHub `releases page`_ and then transfer that archive to the Ansible control
+node. Once we have that archive on our control node, we can install the Sensu
+Go collection by running::
+
+   $ ansible-galaxy collection install path/to/sensu-sensu_go-1.0.0.tar.gz
+
+.. _releases page:
+   https://github.com/sensu/sensu-go-ansible/releases