expand ansible-doc coverage (#74963)

* Expand ansible-doc to tests/filters and fix existing issues

  enable filter/test docs if in single file or companion yaml
  add docs for several filters/tests plugins
  allow .yml companion for docs for other plugins, must be colocated
  verify plugins are valid (not modules, cannot)
  fix 'per collection' filtering
  limit old style deprecation (_ prefix) to builtin/legacy
  start move to pathlib for saner path handling
  moved some funcitons, kept backwards compat shims with deprecation notice

  Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com>
  Co-authored-by: Felix Fontein <felix@fontein.de>
  Co-authored-by: Sandra McCann <samccann@redhat.com>

1 files changed, 12 insertions, 0 deletions

diff --git a/lib/ansible/collections/list.py b/lib/ansible/collections/list.py
index c6af77a364..af3c1cae28 100644
--- a/lib/ansible/collections/list.py
+++ b/lib/ansible/collections/list.py
@@ -12,11 +12,23 @@ from ansible.errors import AnsibleError
 from ansible.collections import is_collection_path
 from ansible.module_utils._text import to_bytes
 from ansible.utils.collection_loader import AnsibleCollectionConfig
+from ansible.utils.collection_loader._collection_finder import _get_collection_name_from_path
 from ansible.utils.display import Display
 
 display = Display()
 
 
+def list_collections(coll_filter=None, search_paths=None, dedupe=False):
+
+    collections = {}
+    for candidate in list_collection_dirs(search_paths=search_paths, coll_filter=coll_filter):
+        if os.path.exists(candidate):
+            collection = _get_collection_name_from_path(candidate)
+            if collection not in collections or not dedupe:
+                collections[collection] = candidate
+    return collections
+
+
 def list_valid_collection_paths(search_paths=None, warn=False):
     """
     Filter out non existing or invalid search_paths for collections