Add documentation for examples in the adjacent documentation

Project Discussions Collection Development
1

Hello,

I’m having trouble making a collection pass ansible-test.
I would like to use Adjacent documentation.
At the moment my troubles are located with the EXAMPLES block.

EXAMPLES:
  - name: Create a project
    scaleway.scaleway.scaleway_account_project:
      access_key: "{{ scw_access_key }}"
      secret_key: "{{ scw_secret_key }}"
      name: "aaaaaa"

This examples creates a fail error that seems to be caused by incorrect yaml but I fail to understand why. Could you add in the documentation for the adjacent documentation an example that contains several examples?

2

Shouldn’t that first line be

EXAMPLES = r'''

rather than

EXAMPLES:

?
And a trailing line with only “'''” on it?
And the body of your example shifted two columns to the left?

3

I’m not including those examples in the python code, I’m adding it inside the yaml as exposed in Adjacent YAML documentation files — Ansible Community Documentation

4

does it work with ansible-doc?

5

@felixfontein @mattclay Do you have more information about this? Is there examples of Yaml adjacent document with several examples that exists? if you need more information about my settings my branch is there ci: add support for ruff format and linting by remyleone · Pull Request #42 · scaleway/ansible · GitHub

6

@bcoca I’m not sure about how to test it using ansible-doc, is there a way to launch ansible-doc in linting mode to find potential errors in adjacent yaml documentation?

7

When I’m on my branch I have the following error:

$ ./venv/bin/ansible-doc -F -vvv
ERROR! Unexpected Exception, this is probably a bug: sequence item 0: expected str instance, NoneType found
the full traceback was:

Traceback (most recent call last):
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/cli/__init__.py", line 646, in cli_executor
    exit_code = cli.run()
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/cli/doc.py", line 935, in run
    docs = self._list_plugins(plugin_type, content)
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/cli/doc.py", line 796, in _list_plugins
    self.plugins.update(list_plugins(plugin_type, coll_filter))
                        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/plugins/list.py", line 198, in list_plugins
    plugins.update(list_collection_plugins(ptype, plugin_collections))
                   ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/plugins/list.py", line 150, in list_collection_plugins
    plugins.update(_list_plugins_from_paths(ptype, dirs, collection))
                   ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/plugins/list.py", line 102, in _list_plugins_from_paths
    plugin_name = get_composite_name(collection, plugin, os.path.dirname(to_native(full_path)), depth)
  File "/Users/rleone/workspace/ansible_collections/scaleway/scaleway/venv/lib/python3.13/site-packages/ansible/plugins/list.py", line 42, in get_composite_name
    return '.'.join(composite)
           ~~~~~~~~^^^^^^^^^^^
TypeError: sequence item 0: expected str instance, NoneType found
8

As of now, and I think it’s just an oversight because there are some bugs that prevent it from working, EXAMPLES can only be a string.

So instead of EXAMPLES: you would need to use EXAMPLES: |.

There is no issue logged yet, but I’ve pinged the appropriate people.

The 2 issues I see are:

  1. ansible-doc loads the sidecar file with the AnsibleLoader which creates custom types, but then attempts to dump the EXAMPLES with yaml.dumps without the Loader
  2. validate-modules assumes that EXAMPLES is always a string, and attempts to execute yaml.loads on it.
9

Can you post the sidecar file or examples section that is causing the issue?

Nevermind, Sivel got me a copy

Without a sample, I’m just guessing that the following patch fixes the ansible-doc side at least:

diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 52ec8a6c7b..7d39beb08f 100755
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@@ -1358,7 +1358,7 @@ class DocCLI(CLI, RoleMixin):
                     text.append(doc.pop('examples').strip())
                 else:
                     try:
-                        text.append(yaml_dump(doc.pop('examples'), indent=2, default_flow_style=False))
+                        text.append(DocCLI._dump_yaml(doc.pop('examples')))
                     except Exception as e:
                         raise AnsibleParserError("Unable to parse examples section", orig_exc=e)
 
@@ -1506,7 +1506,7 @@ class DocCLI(CLI, RoleMixin):
                 text.append(doc.pop('plainexamples').strip())
             else:
                 try:
-                    text.append(yaml_dump(doc.pop('plainexamples'), indent=2, default_flow_style=False))
+                    text.append(DocCLI._dump_yaml(doc.pop('plainexamples')))
                 except Exception as e:
                     raise AnsibleParserError("Unable to parse examples section", orig_exc=e)
10

possible fix ansible-doc fix YAML examples rendering by bcoca · Pull Request #84467 · ansible/ansible · GitHub , right now just ansilbe-doc, probably needs to fix ansible-test also

11

Hi @remyleone

You might want to give a try on andebox by yours truly. Generating the docs is easy as:

andebox docsite -d ~/tmp/mydocsite -o

(the -o will automatically open a browser/tab on the generated documentation).