Modules are not documented properly in Ansible Collection

[displague]

SUMMARY

Per https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_documenting.html
Ansible collection documentation must be defined within each module,

DOCUMENTATION = r'''

https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#module-documenting for more details.

What this project does today is include a docs/ directory (https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#collections-doc-dir) and use https://github.com/linode/ansible-specdoc to generate the module documentation within the .py files.

Neither the docs/ documentation nor the representation of that documentation in the .py files appear in the Ansible Galaxy view:
https://galaxy.ansible.com/ui/repo/published/equinix/cloud/content/module/metal_device/

The one resource that uses the Ansible Galaxy compatible documentation approach is the inventory plugin for Metal Devices: https://galaxy.ansible.com/ui/repo/published/equinix/cloud/content/inventory/metal_device/.

Notice how every other documentation link is empty.

Move the documentation to the modules themselves.

ISSUE TYPE

• Documentation Report

COMPONENT NAME

ANSIBLE VERSION

[displague]

We'll want to make sure that reference links from one piece of documentation to the other use the refence macros: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#format-macros-within-module-documentation

[displague]

I don't know if this docs/ format was ever conventional. If it was there may be scripts or helpers, like ansible-docs, to convert from the old format to the new.

[displague]

The examples and return blocks, which are currently found in the md files, would be documented in this format: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#examples-block

[displague]

My previously stated assumptions about why the collection documentation is not appearing in Ansible Galaxy seems incorrect:
https://github.com/equinix-labs/ansible-collection-equinix/blob/main/plugins/modules/metal_connection.py#L6-L7

As we see here, the module is documented in the format described in the reference links. The problem and question remains - why is this not rendering correctly in Ansible Galaxy?

[t0mk]

@displague I looked around. We use ansible-specdoc to generate those docstrings, just like linode, and modules in their collection are not rendered properly either:
https://galaxy.ansible.com/ui/repo/published/linode/cloud/content/module/instance/

I don't think we can regress to write the docs by hand, it's unfeasible at this point, so the way is to (help) fix it in ansible-specdoc. I will try to find out what the problem is. In the meantime I reported it in ansible-specdoc:
linode/ansible-specdoc#32

I think this is the way to check the doc format:

ansible-doc -M plugins/modules -t module metal_project

Returns

ERROR! module metal_project missing documentation (or could not parse documentation): metal_project did not contain a DOCUMENTATION attribute (/home/tomk/em/ansible_collections/equinix/cloud/plugins/modules/metal_project.py). Unable to parse documentation in python file '/home/tomk/em/ansible_collections/equinix/cloud/plugins/modules/metal_project.py': while parsing a block mapping
  in "<unicode string>", line 3, column 3
did not find expected key
  in "<unicode string>", line 8, column 4. while parsing a block mapping
  in "<unicode string>", line 3, column 3
did not find expected key
  in "<unicode string>", line 8, column 4

[displague]

I noticed that the only inventory or module that does appear in Galaxy is https://github.com/equinix-labs/ansible-collection-equinix/blob/main/docs/inventory/metal_device.rst, which uses Restructured text instead of Markdown (any other significant changes in how this is generated?)

[displague]

https://github.com/a10networks/a10-acos-axapi is an example of a project whose documentation is shown in Galaxy: https://galaxy.ansible.com/ui/repo/published/a10/acos_axapi/content/module/a10_aam_aaa_policy/

(given as the example only because they are alphabetically at the top of the list)

[displague]

I wonder if ansible-doc is sensitive to the presence of r (as specified in the guides and seen in the A10 code: https://github.com/a10networks/a10-acos-axapi/blob/master/plugins/modules/a10_aam_aaa_policy.py#L12):

DOCUMENTATION = r'''

[t0mk]

problem seem to be the RETURN block. We have result_sample defined as a list of strings, which is processed into a messy string not liked by ansible-doc. When I change the result_sample to simple dict, more clean RETURN is generated and is accepted by ansible-doc.

I had to change
https://github.com/equinix-labs/ansible-collection-equinix/blob/d4665b5880ff5509145b2710ac8f62a187dad9f3/plugins/modules/metal_project.py#L175

to

result_sample = {
  "backend_transfer_enabled": False,
  "changed": False,
  "customdata": {},
  "description": "",
  "id": "7624f0f7-75b6-4271-bc64-632b80f87de2",
  "name": "ansible-integration-test-project-csle6t2y-project1_renamed",
  "organization_id": "70c2f878-9f32-452e-8c69-ab15480e1d99",
  "payment_method_id": "845b45a3-c565-47e5-b9b6-a86204a73d29"
}

and call ansible-specdoc -ji plugins/modules/metal_project.py.

In short, RETURN must be clear and valid YAML.

[github-actions]

This issue has been resolved in version 0.4.1 🎉