An earlier optimization of ansible-doc -l caused failures. (#47012)

* An earlier optimization of ansible-doc -l caused failures.

The optimization quickly searches the plugin code for short_description
fields and then uses that in the -l output.  The searching was a bit too
naive and ended up pulling out malformed yaml.  This caused those
plugins to be omitted from the list of plugins of that type with
a warning that their documentation strings were wrong.

This change makes the documentation parser aware that the documentation
string could have a relative indent for all of its fields which makes it
robust in the face of this particular problem.

* Don't search for space after short_description:

Any whitespace would be valid.  In particular newline

changelogs/fragments/plugin-docs-list-fix.yaml

@@ -0,0 +1,3 @@
+---
+bugfixes:
+- 'Fixed an issue with ansible-doc -l failing when parsing some plugin documentation.'

lib/ansible/parsing/plugin_docs.py

@@ -90,18 +90,29 @@ def read_docstub(filename):
     """
 
     t_module_data = open(filename, 'r')
+    in_documentation = False
     capturing = False
+    indent_detection = ''
     doc_stub = []
 
     for line in t_module_data:
-        # start capturing the stub until indentation returns
-        if capturing and line[0] == ' ':
-            doc_stub.append(line)
-        elif capturing and line[0] != ' ':
-            break
-        if 'short_description:' in line:
-            capturing = True
-            doc_stub.append(line)
+        if in_documentation:
+            # start capturing the stub until indentation returns
+            if capturing and line.startswith(indent_detection):
+                doc_stub.append(line)
+
+            elif capturing and not line.startswith(indent_detection):
+                break
+
+            elif line.lstrip().startswith('short_description:'):
+                capturing = True
+                # Detect that the short_description continues on the next line if it's indented more
+                # than short_description itself.
+                indent_detection = ' ' * (len(line) - len(line.lstrip()) + 1)
+                doc_stub.append(line)
+
+        elif line.startswith('DOCUMENTATION') and '=' in line:
+            in_documentation = True
 
     short_description = r''.join(doc_stub).strip().rstrip('.')
     data = AnsibleLoader(short_description, file_name=filename).get_single_data()