# Add documentation for examples in the adjacent documentation **URL:** \ **Category:** Collection Development\ **Created:** [December 11, 2024, 11:05am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048 "2024-12-11T11:05:25Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![remyleone](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/remyleone/32/5200_2.png) [@remyleone](https://forum.ansible.com/u/remyleone)\ **Post date:** [December 11, 2024, 11:05am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/1 "2024-12-11T11:05:25Z")
Hello, I’m having trouble making a collection pass ansible-test. I would like to use [Adjacent documentation](https://docs.ansible.com/ansible/latest/dev_guide/sidecar.html). At the moment my troubles are located with the [EXAMPLES](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#examples-block) block. ```yaml 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? ---
**Author:** ![utoddl](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/utoddl/32/249_2.png) [@utoddl](https://forum.ansible.com/u/utoddl)\ **Post date:** [December 11, 2024, 11:42am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/2 "2024-12-11T11:42:21Z")
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? ---
**Author:** ![remyleone](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/remyleone/32/5200_2.png) [@remyleone](https://forum.ansible.com/u/remyleone)\ **Post date:** [December 11, 2024, 2:13pm UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/3 "2024-12-11T14:13:49Z")
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](https://docs.ansible.com/ansible/latest/dev_guide/sidecar.html) ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [December 11, 2024, 5:20pm UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/4 "2024-12-11T17:20:03Z")
does it work with `ansible-doc`? ---
**Author:** ![remyleone](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/remyleone/32/5200_2.png) [@remyleone](https://forum.ansible.com/u/remyleone)\ **Post date:** [December 12, 2024, 10:21am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/5 "2024-12-12T10:21:09Z")
@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](https://github.com/scaleway/ansible/pull/42/files) ---
**Author:** ![remyleone](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/remyleone/32/5200_2.png) [@remyleone](https://forum.ansible.com/u/remyleone)\ **Post date:** [December 12, 2024, 10:25am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/6 "2024-12-12T10:25:24Z")
@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? ---
**Author:** ![remyleone](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/remyleone/32/5200_2.png) [@remyleone](https://forum.ansible.com/u/remyleone)\ **Post date:** [December 12, 2024, 10:28am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/7 "2024-12-12T10:28:45Z")
When I’m on my branch I have the following error: ```auto $ ./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 ``` ---
**Author:** ![sivel](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/sivel/32/1198_2.png) [@sivel](https://forum.ansible.com/u/sivel)\ **Post date:** [December 12, 2024, 3:26pm UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/8 "2024-12-12T15:26:32Z")
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. ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [December 12, 2024, 3:42pm UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/9 "2024-12-12T15:42:39Z")
> 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: ```auto 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) ``` ---
**Author:** ![bcoca](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/bcoca/32/9269_2.png) [@bcoca](https://forum.ansible.com/u/bcoca)\ **Post date:** [December 12, 2024, 4:22pm UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/10 "2024-12-12T16:22:11Z")
possible fix [ansible-doc fix YAML examples rendering by bcoca · Pull Request #84467 · ansible/ansible · GitHub](https://github.com/ansible/ansible/pull/84467) , right now just ansilbe-doc, probably needs to fix ansible-test also ---
**Author:** ![russoz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/russoz/32/127_2.png) [@russoz](https://forum.ansible.com/u/russoz)\ **Post date:** [December 13, 2024, 12:29am UTC](https://forum.ansible.com/t/add-documentation-for-examples-in-the-adjacent-documentation/39048/11 "2024-12-13T00:29:13Z")
Hi @remyleone You might want to give a try on [`andebox`](https://pypi.org/project/andebox/) by yours truly. Generating the docs is easy as: ```bash andebox docsite -d ~/tmp/mydocsite -o ``` (the `-o` will automatically open a browser/tab on the generated documentation).