From 7caa7e1162038a323eaf577995db1a06c2442eff Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 3 Sep 2020 22:42:31 +0300 Subject: [PATCH] Docsite: improve developing_modules_documenting.rst (#71590) (#71613) * add necessary dots to returns descriptions (cherry picked from commit bfba0ffc452b6817ce82e68cfb4a06a1debff15c) --- .../rst/dev_guide/developing_modules_documenting.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 02fa54c9bde..2c242e9e9ee 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -331,13 +331,15 @@ Per playbook best practices, each example should include a ``name:`` line:: EXAMPLES = r''' - name: Ensure foo is installed - modulename: + namespace.collection.modulename: name: foo state: present ''' The ``name:`` line should be capitalized and not include a trailing dot. +Use a fully qualified collection name (FQCN) as a part of the module's name like in the example above. For modules in ``ansible-base``, use the ``ansible.builtin.`` identifier, for example ``ansible.builtin.debug``. + If your examples use boolean options, use yes/no values. Since the documentation generates boolean values as yes/no, having the examples use these values as well makes the module documentation more consistent. If your module returns facts that are often needed, an example of how to use them can be helpful. @@ -393,12 +395,12 @@ Here are two example ``RETURN`` sections, one with three simple fields and one w RETURN = r''' packages: - description: Information about package requirements + description: Information about package requirements. returned: success type: complex contains: missing: - description: Packages that are missing from the system + description: Packages that are missing from the system. returned: success type: list sample: