Closed displague closed 4 months ago
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
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.
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
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?
@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: https://github.com/linode/ansible-specdoc/issues/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
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?)
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)
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'''
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.
This issue has been resolved in version 0.4.1 :tada:
SUMMARY
Per https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_documenting.html Ansible collection documentation must be defined within each module,
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
COMPONENT NAME
ANSIBLE VERSION