MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129

docs/docsite/rst/collections_guide/collections_installing.rst

@@ -16,7 +16,62 @@ See `Getting started with Execution Environments <https://ansible.readthedocs.io
 Installing collections with ``ansible-galaxy``
 ----------------------------------------------
 
-.. include:: ../shared_snippets/installing_collections.txt
+
+By default, ``ansible-galaxy collection install`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the
+:file:`ansible.cfg` file under :ref:`galaxy_server`). You do not need any further configuration.
+By default, Ansible installs the collection in ``~/.ansible/collections`` under the ``ansible_collections`` directory.
+
+See :ref:`Configuring the ansible-galaxy client <galaxy_server_config>` if you are using any other Galaxy server, such as Red Hat Automation Hub.
+
+To install a collection hosted in Galaxy:
+
+.. code-block:: bash
+
+   ansible-galaxy collection install my_namespace.my_collection
+
+To upgrade a collection to the latest available version from the Galaxy server you can use the ``--upgrade`` option:
+
+.. code-block:: bash
+
+   ansible-galaxy collection install my_namespace.my_collection --upgrade
+
+You can also directly use the tarball from your build:
+
+.. code-block:: bash
+
+   ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
+
+You can build and install a collection from a local source directory. The ``ansible-galaxy`` utility builds the collection using the ``MANIFEST.json`` or ``galaxy.yml``
+metadata in the directory.
+
+.. code-block:: bash
+
+   ansible-galaxy collection install /path/to/collection -p ./collections
+
+You can also install multiple collections in a namespace directory.
+
+.. code-block:: text
+
+   ns/
+   ├── collection1/
+   │   ├── MANIFEST.json
+   │   └── plugins/
+   └── collection2/
+       ├── galaxy.yml
+       └── plugins/
+
+.. code-block:: bash
+
+   ansible-galaxy collection install /path/to/ns -p ./collections
+
+.. note::
+    The install command automatically appends the path ``ansible_collections`` to the one specified  with the ``-p`` option unless the
+    parent directory is already in a folder called ``ansible_collections``.
+
+
+When using the ``-p`` option to specify the install path, use one of the values configured in :ref:`COLLECTIONS_PATHS`, as this is
+where Ansible itself will expect to find collections. If you don't specify a path, ``ansible-galaxy collection install`` installs
+the collection to the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``
 
 .. _installing_signed_collections:
 
@@ -114,6 +169,32 @@ Downloading a collection for offline use
 
 .. include:: ../shared_snippets/download_tarball_collections.txt
 
+.. _collection_local_install:
+
+Installing collections adjacent to playbooks
+--------------------------------------------
+
+You can install collections locally next to your playbooks inside your project instead of in a global location on your system or on your AWX.
+This approach has these added benefits:
+* Ensures that all users of the project use the same collection version.
+* Using self-contained projects makes it easy to move across different environments. Increased portability also reduces overhead when setting up new environments. This is a benefit when deploying Ansible playbooks in cloud environments.
+* Managing colelctions locally lets you version them along with your playbooks.
+* Installing collections locally isolates them from global installations in environments that have multiple projects.
+
+Here is an example of keeping a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure.
+
+.. code-block:: text
+
+    ./
+    ├── play.yml
+    ├── collections/
+    │   └── ansible_collections/
+    │               └── my_namespace/
+    │                   └── my_collection/<collection structure lives here>
+
+
+See :ref:`collection_structure` for details on the collection directory structure.
+
 Installing a collection from source files
 -----------------------------------------