0

I am writing my own ansible modules which shares the same document across 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 .. 

library        = /etc/ansible/library/modules

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

Zeitounator
  • 38,476
  • 7
  • 53
  • 66
Alok Ranjan
  • 158
  • 10
  • 1
    Can you please edit your question and review the formating, especially for the code blocks. This is really hard to read. Thanks. – Zeitounator May 20 '20 at 11:17
  • Well if you edit without taking the time to understand the formatting bar on top of the edit field, reading the help, looking at other correctly formatted questions/answers on the site (simply click on the edit button anywhere to see how it looks like)... there is almost no chance you can achieve a better result than on your first try. I edited for you. Please have a look, understand how to format correctly for you next questions and make sure the code is aligned with your original one. Fix it if needed. – Zeitounator May 21 '20 at 14:15
  • Unless you really want to later contribute to ansible core or propose your module as a core one (good luck ;)), I strongly suggest you don't loose time and mess things up trying to insert your module in ansible's defaults system path. You can instead develop your module inside a [collection](https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#developing-collections). The [`community.general` collection](https://github.com/ansible-collections/community.general) is one example you can study. It contains doc fragments as you want to implement (see plugin/doc_fragments) – Zeitounator May 21 '20 at 15:34
  • Thanks for the feedback. And really sorry for my bad edits. Should have done my homework – Alok Ranjan May 23 '20 at 14:05

0 Answers0