From 61ae6424a38a683b593870cb087d193be5784cc5 Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Wed, 17 Oct 2018 08:15:59 -0700 Subject: [PATCH] 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 --- .../fragments/plugin-docs-list-fix.yaml | 3 +++ lib/ansible/parsing/plugin_docs.py | 27 +++++++++++++------ 2 files changed, 22 insertions(+), 8 deletions(-) create mode 100644 changelogs/fragments/plugin-docs-list-fix.yaml diff --git a/changelogs/fragments/plugin-docs-list-fix.yaml b/changelogs/fragments/plugin-docs-list-fix.yaml new file mode 100644 index 00000000000..19ff8eef68a --- /dev/null +++ b/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.' diff --git a/lib/ansible/parsing/plugin_docs.py b/lib/ansible/parsing/plugin_docs.py index dd1e038d9c4..fe0057f8a7a 100644 --- a/lib/ansible/parsing/plugin_docs.py +++ b/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()