1 files changed, 100 insertions, 0 deletions
diff --git a/docs/docsite/rst/dev_guide/sidecar.rst b/docs/docsite/rst/dev_guide/sidecar.rst
new file mode 100644
index 0000000..ccf3aa7
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/sidecar.rst
@@ -0,0 +1,100 @@
+.. _adjacent_yaml_doc:
+
+*********************************
+Adjacent YAML documentation files
+*********************************
+
+.. contents::
+   :local:
+
+YAML documentation for plugins
+------------------------------
+For most Ansible plugins, the documentation is in the same file as the code. This approach does not work for cases when:
+
+  * Multiple plugins are defined in the same file, such as tests and filters.
+  * Plugins are written in a language other than Python (modules).
+
+These cases require plugins to provide documentation in an adjacent ``.py`` file. As of ansible-core 2.14, you can provide documentation as adjacent YAML files instead.
+The format of a YAML documentation file is nearly identical to its Python equivalent, except it is pure YAML.
+
+
+YAML format
+-----------
+In Python each section is a variable ``DOCUMENTATION = r""" ... """`` while in YAML it is a mapping key ``DOCUMENTATION: ...``.
+
+Here is a longer example that shows documentation as embedded in a Python file:
+
+.. code-block:: python
+
+  DOCUMENTATION = r'''
+    description: something
+    options:
+      option_name:
+        description: describe this config option
+        default: default value for this config option
+        env:
+          - name: NAME_OF_ENV_VAR
+        ini:
+          - section: section_of_ansible.cfg_where_this_config_option_is_defined
+            key: key_used_in_ansible.cfg
+        vars:
+          - name: name_of_ansible_var
+          - name: name_of_second_var
+            version_added: X.x
+        required: True/False
+        type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath
+        version_added: X.x
+  '''
+
+  EXAMPLES = r'''
+    # TODO: write examples
+  '''
+
+This example shows the same documentation in YAML format:
+
+.. code-block:: YAML
+
+  DOCUMENTATION:
+    description: something
+    options:
+      option_name:
+        description: describe this config option
+        default: default value for this config option
+        env:
+          - name: NAME_OF_ENV_VAR
+        ini:
+          - section: section_of_ansible.cfg_where_this_config_option_is_defined
+            key: key_used_in_ansible.cfg
+        vars:
+          - name: name_of_ansible_var
+          - name: name_of_second_var
+            version_added: X.x
+        required: True/False
+        type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath
+        version_added: X.x
+
+  EXAMPLES: # TODO: write examples
+
+As the examples above show, Python variables already contain YAML. The main change to use YAML documentation is to simply move the YAML out of such variables.
+
+ Any adjacent YAML documentation files must be in the same directory as the plugin or module that they document. This means the documentation is available in any directory that contains the plugins or modules.
+
+
+Supported plugin types
+----------------------
+YAML documentation is mainly intended for filters, tests and modules. While it is possible to use with other plugin types, Ansible always recommends having documentation in the same file as the code for most cases.
+
+.. seealso::
+
+   :ref:`list_of_collections`
+       Browse existing collections, modules, and plugins
+   :ref:`developing_api`
+       Learn about the Python API for task execution
+   :ref:`developing_inventory`
+       Learn about how to develop dynamic inventory sources
+   :ref:`developing_modules_general`
+       Learn about how to write Ansible modules
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   :ref:`communication_irc`
+       How to join Ansible chat channels