Clarify collection paths in docs (#72510)

* Clarify collection paths in docs, fix rst syntax, rephrase docs about using collection from folder/local git

Co-authored-by: Felix Fontein <felix@fontein.de>

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -400,6 +400,8 @@ You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your
 expect to find collections when attempting to use them. If you don't specify a path value, ``ansible-galaxy collection install``
 installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``.
 
+If you want to use a collection directly out of a checked out git repository, see :ref:`hacking_collections`.
+
 Next, try using the local collection inside a playbook. For examples and more details see :ref:`Using collections <using_collections>`
 
 .. _collections_scm_install:

lib/ansible/config/base.yml

@@ -243,7 +243,12 @@ COLLECTIONS_SCAN_SYS_PATH:
   - {key: collections_scan_sys_path, section: defaults}
 COLLECTIONS_PATHS:
   name: ordered list of root paths for loading installed Ansible collections content
-  description: Colon separated paths in which Ansible will search for collections content.
+  description: >
+    Colon separated paths in which Ansible will search for collections content.
+    Collections must be in nested *subdirectories*, not directly in these directories.
+    For example, if ``COLLECTIONS_PATHS`` includes ``~/.ansible/collections``,
+    and you want to add ``my.collection`` to that directory, it must be saved as
+    ``~/.ansible/collections/ansible_collections/my/collection``.
   default: ~/.ansible/collections:/usr/share/ansible/collections
   type: pathspec
   env: