documented plugin documentation on documenting

Apply suggestions from code review
Move some comment to 'common snippet' to be included in both plugin and module pages

Co-authored-by: Abhijeet Kasurde <[email protected]>

Author: bcoca

docs/docsite/rst/community/collection_contributors/collection_requirements.rst

@@ -532,7 +532,9 @@ To be included in the `ansible` package, collections must meet the following cri
 * `Collection requirements <https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_requirements.html>`_ (this document).
 
   * The `Collection Inclusion Criteria Checklist <https://github.com/ansible-collections/overview/blob/main/collection_checklist.md>`_ covers most of the criteria from this document.
-* :ref:`Ansible documentation format <module_documenting>` and the :ref:`style guide <style-guide>`.
+* :ref:`Ansible module documentation format <module_documenting>`.
+* :ref:`Ansible plugin documentation format <plugins_documenting>`.
+* And the :ref:`style guide <style-guide>` for both.
 * To pass the Ansible :ref:`sanity tests <testing-sanity>`.
 * To have :ref:`unit <unit-tests>`_and / or :ref:`integration tests <integration-tests>` according to the corresponding sections of this document.
 

docs/docsite/rst/community/documentation_contributions.rst

@@ -235,5 +235,5 @@ The Documentation Working Group (DaWGs) meets weekly on Tuesdays in the Docs cha
 
 .. seealso::
    :ref:`More about testing module documentation <testing_module_documentation>`
-
    :ref:`More about documenting modules <module_documenting>`
+   :ref:`More about documenting plugins <plugins_documenting>`

docs/docsite/rst/community/maintainers_guidelines.rst

@@ -147,7 +147,7 @@ Maintaining good collection documentation
 
 Maintainers look after the collection documentation to ensure it matches the :ref:`style_guide`. This includes keeping the following documents accurate and updated regularly:
 
-* Collection module and plugin documentation that adheres to the :ref:`Ansible documentation format <module_documenting>`.
+* Collection module and plugin documentation that adheres to the :ref:`Ansible module documentation format <module_documenting>` and :ref:`Ansible plugin documentation format <plugins_documenting>`.
 * Collection user guides that follow the :ref:`Collection documentation format <collections_doc_dir>`.
 * Repository files that includes at least a ``README`` and ``CONTRIBUTING`` file.
 

docs/docsite/rst/dev_guide/ansible_index.rst

@@ -46,6 +46,7 @@ Find the task that best describes what you want to do:
    * I want to :ref:`debug my module code <debugging_modules>`.
    * I want to :ref:`add tests <developing_testing>`.
    * I want to :ref:`document my module <module_documenting>`.
+   * I want to :ref:`document my plugin <plugins_documenting>`.
    * I want to :ref:`document my set of modules for a network platform <documenting_modules_network>`.
    * I want to follow :ref:`conventions and tips for clean, usable module code <developing_modules_best_practices>`.
    * I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.

docs/docsite/rst/dev_guide/core_index.rst

@@ -43,6 +43,7 @@ Find the task that best describes what you want to do:
    * I want to :ref:`debug my module code <debugging_modules>`.
    * I want to :ref:`add tests <developing_testing>`.
    * I want to :ref:`document my module <module_documenting>`.
+   * I want to :ref:`document my plugin <plugins_documenting>`.
    * I want to :ref:`document my set of modules for a network platform <documenting_modules_network>`.
    * I want to follow :ref:`conventions and tips for clean, usable module code <developing_modules_best_practices>`.
    * I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.

docs/docsite/rst/dev_guide/developing_collections_documenting.rst

@@ -7,7 +7,7 @@ Documenting collections
 Documenting modules and plugins
 ===============================
 
-Documenting modules is thoroughly documented in :ref:`module_documenting`. Plugins can be documented the same way as modules, that is with ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN`` blocks.
+A comprehensive guide to documenting modules can be found in :ref:`module_documenting`. Plugins can be documented similarly to modules :ref:`plugins_documenting`, that is with ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN`` blocks.
 
 Documenting roles
 =================

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -252,73 +252,11 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 
 .. _module_documents_linking:
 
-Linking within module documentation
------------------------------------
-
-You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:
-
-* ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
-* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
-* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``.  Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
-* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``. A FQCN **must** be used, short names will create broken links; use ``ansible.builtin`` for modules in ansible-core.
-* ``P()`` for plugin names. For example: ``See also P(ansible.builtin.file#lookup) or P(community.general.json_query#filter)``. This can also reference roles: ``P(community.sops.install#role)``. This is supported since ansible-core 2.15. FQCNs must be used; use ``ansible.builtin`` for plugins in ansible-core.
-
-.. note::
-
-  For links between modules and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ to convert ``R()`` and ``M()`` to the correct links.
-
-.. note::
-  To refer to a group of modules in a collection, use ``R()``.  When a collection is not the right granularity, use ``C(..)``:
-
-    - ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.``
-    - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
-
-.. note::
-
-   Because it stands out better, use ``seealso`` for general references over the use of notes or adding links to the description.
+.. include:: document_linking.rst
 
 .. _semantic_markup:
 
-Semantic markup within module documentation
--------------------------------------------
-
-You can use semantic markup to highlight option names, option values, and environment variables. The markup processor formats these highlighted terms in a uniform way. With semantic markup, we can modify how the output looks without changing underlying code.
-
-The correct formats for semantic markup are as follows:
-
-* ``O()`` for option names, whether mentioned alone or with values. For example: ``Required if O(state=present).`` and ``Use with O(force) to require secure access.``
-* ``V()`` for option values when mentioned alone. For example: ``Possible values include V(monospace) and V(pretty).``
-* ``RV()`` for return value names, whether mentioned alone or with values. For example: ``The module returns RV(changed=true) in case of changes.`` and ``Use the RV(stdout) return value for standard output.``
-* ``E()`` for environment variables. For example: ``If not set, the environment variable E(ACME_PASSWORD) will be used.``
-
-The parameters for these formatting functions can use escaping with backslashes: ``V(foo(bar="a\\b"\), baz)`` results in the formatted value ``foo(bar="a\b"), baz)``.
-
-Rules for using ``O()`` and ``RV()`` are very strict. You must follow syntax rules so that documentation renderers can create hyperlinks for the options and return values, respectively.
-
-The allowed syntaxes are as follows:
-- To reference an option for the current plugin/module, or the entrypoint of the current role (inside role entrypoint documentation), use ``O(option)`` and ``O(option=name)``.
-- To reference an option for another entrypoint ``entrypoint`` from inside role documentation, use ``O(entrypoint:option)`` and ``O(entrypoint:option=name)``. The entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint.
-- To reference an option for *another* plugin/module ``plugin.fqcn.name`` of type ``type``, use ``O(plugin.fqcn.name#type:option)`` and ``O(plugin.fqcn.name#type:option=name)``. For modules, use ``type=module``. The FQCN and plugin type can be ignored by the documentation renderer, turned into a link to that plugin, or even directly to the option of that plugin.
-- To reference an option for entrypoint ``entrypoint`` of *another* role ``role.fqcn.name``, use ``O(role.fqcn.name#role:entrypoint:option)`` and ``O(role.fqcn.name#role:entrypoint:option=name)``. The FQCN and entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint.
-- To reference options that do not exist (for example, options that were removed in an earlier version), use ``O(ignore:option)`` and ``O(ignore:option=name)``. The ``ignore:`` part will not be shown to the user by documentation rendering.
-
-Option names can refer to suboptions by listing the path to the option separated by dots. For example, if you have an option ``foo`` with suboption ``bar``, then you must use ``O(foo.bar)`` to reference that suboption. You can add array indications like ``O(foo[].bar)`` or even ``O(foo[-1].bar)`` to indicate specific list elements. Everything between ``[`` and ``]`` pairs will be ignored to determine the real name of the option. For example, ``O(foo[foo | length - 1].bar[])`` results in the same link as ``O(foo.bar)``, but the text ``foo[foo | length - 1].bar[]`` displays instead of ``foo.bar``.
-
-The same syntaxes can be used for ``RV()``, except that these will refer to return value names instead of option names; for example ``RV(ansible.builtin.service_facts#module:ansible_facts.services)`` refers to the :ansretval:`ansible.builtin.service_facts#module:ansible_facts.services` fact returned by the :ansplugin:`ansible.builtin.service_facts module <ansible.builtin.service_facts#module>`.
-
-Format macros within module documentation
------------------------------------------
-
-While it is possible to use standard Ansible formatting macros to control the look of other terms in module documentation, you should do so sparingly.
-
-Possible macros include the following:
-
-* ``C()`` for ``monospace`` (code) text. For example: ``This module functions like the unix command C(foo).``
-* ``B()`` for bold text.
-* ``I()`` for italic text.
-* ``HORIZONTALLINE`` for a horizontal rule (the ``<hr>`` html tag) to separate long descriptions.
-
-Note that ``C()``, ``B()``, and ``I()`` do **not allow escaping**, and thus cannot contain the value ``)`` as it always ends the formatting sequence. If you need to use ``)`` inside ``C()``, we recommend to use ``V()`` instead; see the above section on semantic markup.
+.. include:: semantic_markup.rst
 
 .. _module_docs_fragments:
 

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -89,7 +89,7 @@ If you need to populate settings explicitly, use a ``self.set_options()`` call.
 
 Configuration sources follow the precedence rules for values in Ansible. When there are multiple values from the same category, the value defined last takes precedence. For example, in the above configuration block, if both ``name_of_ansible_var`` and ``name_of_second_var`` are defined, the value of the ``option_name`` option will be the value of ``name_of_second_var``. Refer to :ref:`general_precedence_rules` for further information.
 
-Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) should include well-formed doc strings. If you inherit from a plugin, you must document the options it takes, either through a documentation fragment or as a copy. See :ref:`module_documenting` for more information on correct documentation. Thorough documentation is a good idea even if you're developing a plugin for local use.
+Plugins that support embedded documentation (see :ref:`ansible-doc` for the list) should include well-formed doc strings. If you inherit from a plugin, you must document the options it takes, either through a documentation fragment or as a copy. See :ref:`plugins_documenting` for more information on correct documentation. Thorough documentation is a good idea even if you're developing a plugin for local use.
 
 In ansible-core 2.14 we added support for documenting filter and test plugins. You have two options for providing documentation:
   - Define a Python file that includes inline documentation for each plugin.

docs/docsite/rst/dev_guide/document_linking.rst

@@ -0,0 +1,25 @@
+Linking within plugin documentation
+-----------------------------------
+
+You can link from your plugin or module documentation to other plugin/module, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:
+
+* ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
+* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
+* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``.  Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
+* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``. A FQCN **must** be used, short names will create broken links; use ``ansible.builtin`` for modules in ansible-core.
+* ``P()`` for plugin names. For example: ``See also P(ansible.builtin.file#lookup) or P(community.general.json_query#filter)``. This can also reference roles: ``P(community.sops.install#role)``. This is supported since ansible-core 2.15. FQCNs must be used; use ``ansible.builtin`` for plugins in ansible-core.
+
+.. note::
+
+  For links between pluigins and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_ to convert ``R()`` and ``M()`` to the correct links.
+
+.. note::
+  To refer to a group of modules in a collection, use ``R()``.  When a collection is not the right granularity, use ``C(..)``:
+
+    - ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.``
+    - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
+
+.. note::
+
+   Because it stands out better, use ``seealso`` for general references over the use of notes or adding links to the description.
+