how to use extends_documentation_fragment. getting error while using it

[alok ranjan]

Hi ,

I am new to ansible and this is my first ansible project. I am writing my own ansible modules which shares the same document acroos multiple modules which i need to develop.

As per the ansible website https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html we can use extends_documentation_fragment.

After going through the web link this is what i did on my centos (ansible controller)

i create a new doc file (alokdoc.py) with below content.

class ModuleDocFragment(object):

    DOCUMENTATION = r'''

    array_ip:

      description:

      - "The storage system IP address."

      required: True

    array_password:

      description:

      - "The storage system password."

      required: True

    array_username:

      description:

      - "The storage system user name."

      required: True

    '''

I saved this under the following directory "/usr/lib/python3.6/site-packages/ansible/plugins/doc_fragments" as "alokdoc.py"

Now in my ansible module ,namely, alok_module1.py, located under /etc/ansible/library/modules , i wrote the below

DOCUMENTATION = r'''

---

author: "alok.ranjan@****.com"

description: "my first module"

module: alok_module1

extends_documentation_fragment:

    - alokdoc

.

.

.

Also, in my ansible.cfg file i have these two variables enabled ..

# by alok

library        = /etc/ansible/library/modules:/usr/lib/python3.6/site-packages/ansible/plugins/doc_fragments

module_utils = /usr/lib/python3.6/site-packages/ansible/module_utils

When i run the below command i get error

ansible-doc -t module "alok_module1.py" ERROR! module alok_module1 missing documentation (or could not parse documentation): unknown doc_fragment(s) in file /etc/ansible/library/modules/alok_module1.py: alokdoc

Why am i getting this error. what am i missing??

Thanks,

Alok

[Brian Coca]

you are missing `options:` in your fragment, you are listing them
directly at top level which won't be understood.

```

class ModuleDocFragment(object):

DOCUMENTATION = r'''

options:

array_ip:
description:
- "The storage system IP address."
required: True
array_password:
description:
- "The storage system password."
required: True
array_username:
description:
- "The storage system user name."
required: True
'''

```


--
----------
Brian Coca