ansible-doc fails to parse plugin docs

[gravesm]

Summary

When I try to run ansible-doc on the milestone branch (same result on devel) it fails when the token DOCUMENTATION is used anywhere else in the plugin. I believe #74963 introduced this bug. We initially saw this on the milestone branch sanity test failures for the kubernetes.core collection. https://github.com/ansible-collections/kubernetes.core/blob/95e2add65b4ade93a7ad770a8aa0386f90a9c831/plugins/connection/kubectl.py#L212 is what trips it up. As best I can tell, the new code looks for a DOCUMENTATION token anywhere and then uses the next string token as the doc string. In this case, it's "{0}_command" a few lines down.

Issue Type

Bug Report

Component Name

ansible-doc

Ansible Version

$ ansible --version
ansible [core 2.14.0.dev0] (milestone 2cc74b04c4) last updated 2022/05/05 08:26:56 (GMT -400)
  config file = None
  configured module search path = ['/home/mgraves/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/mgraves/git/ansible/lib/ansible
  ansible collection location = /home/mgraves/git:/home/mgraves/.ansible/collections
  executable location = /home/mgraves/git/ansible/bin/ansible
  python version = 3.8.8 (default, Mar  5 2021, 11:47:01) [GCC 10.2.1 20210110] (/home/mgraves/git/ansible/venv/bin/python)
  jinja version = 3.0.3
  libyaml = True

Configuration

$ ansible-config dump --only-changed
COLLECTIONS_PATHS(env: ANSIBLE_COLLECTIONS_PATH) = ['/home/mgraves/git', '/home/mgraves/.ansible/collections']
CONFIG_FILE() = None

OS / Environment

Debian 11

Steps to Reproduce

Using the latest release of kubernetes.core (2.3.1):

$ ansible-doc -t connection kubernetes.core.kubectl
ERROR! connection kubernetes.core.kubectl missing documentation (or could not parse documentation): did not find expected <document start>
  in "<unicode string>", line 1, column 4

You can also see similar failures for a really simple plugin like:

DOCUMENTATION = r'''
    name: foo
    description:
      - foo module
'''

class Foo:
    DOCUMENTATION = None
    def __init__(self):
        foo = "bar"

Expected Results

I expected the plugin documentation to be generated.

Actual Results

ERROR! connection kubernetes.core.kubectl missing documentation (or could not parse documentation): did not find expected <document start>
  in "<unicode string>", line 1, column 4

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:

• bin/ansible-doc

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help