1. ansible
  2. Commit 959637ff59681250fe62c8e0cc7d81989cdc13f5
Browse code

How to document your module (#21021)

* How to document your module

* Remove blank lines

* note:: Versions should be strings

* requirements on the host that executes the module.

* option names & option values

* Feedback

* formatting

* Scott's final feedback

John R Barker authored on 2017/02/10 21:15:55
Showing 2 changed files
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
History View file @ 959637f
... ... 
@@ -3,15 +3,16 @@
3 3 
 Documenting Your Module
4 4 
 ```````````````````````
5 5
6 
-All modules included in the CORE distribution must have a
7 
-``DOCUMENTATION`` string. This string MUST be a valid YAML document
6 
+The online module documentation is generated from the modules themselves.
7 
+As the module documentation is generated from documentation strings contained in the modules, all modules included with Ansible must have a ``DOCUMENTATION`` string.
8 
+This string must be a valid YAML document
8 9 
 which conforms to the schema defined below. You may find it easier to
9 10 
 start writing your ``DOCUMENTATION`` string in an editor with YAML
10 11 
 syntax highlighting before you include it in your Python file.
11 12
12 13
13 
-Example
14 
-'''''''
14 
+DOCUMENTATION Block
15 
+'''''''''''''''''''
15 16
16 17 
 See an example documentation string in the checkout under `examples/DOCUMENTATION.yml <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_.
17 18
... ... 
@@ -29,30 +30,86 @@ Include it in your module file like this:
29 29 
     # ... snip ...
30 30 
     '''
31 31
32 
-The ``description``, and ``notes`` fields
33 
-support formatting with some special macros.
34 32
35 
-These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()``
36 
-for URL, module, italic, and constant-width respectively. It is suggested
37 
-to use ``C()`` for file and option names, and ``I()`` when referencing
38 
-parameters; module names should be specified as ``M(module)``.
33 
+The following fields can be used and are all required unless specified otherwise:
34 
+
35 
+* ``module:``
36 
+  The name of the module. This must be the same as the filename, without the ``.py`` extension.
37 
+* ``short_description:``
38 
+
39 
+  * A short description which is displayed on the :doc:`../list_of_all_modules` page and ``ansible-doc -l``.
40 
+  * As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
41 
+  * Unlike ``description:`` this field should not have a trailing full stop.
42 
+* ``description:``
43 
+  * A detailed description (generally two or more sentences).
44 
+  * Must be written in full sentences, i.e. with capital letters and fullstops.
45 
+  * Shouldn't mention the name module.
46 
+* ``version_added:``
47 
+  The version of Ansible when the module was added.
48 
+  This is a `string`, and not a float, i.e. ``version_added: "2.1"``
49 
+* ``author:``
50 
+  Name of the module author in the form ``First Last (@GitHubID)``. Use a multi-line list if there is more than one author.
51 
+* ``options:``
52 
+  One per module argument
53 
+
54 
+  * ``description:``
55 
+
56 
+    * Detailed explanation of what this option does. It should be written in full sentences.
57 
+    * Should not list the options values (that's what ``choices:`` is for, though it should explain `what` the values do if they aren't obvious.
58 
+    * If an argument takes both True)/False and Yes)/No, the documentation should use True and False.
59 
+    * If an optional parameter is sometimes required this need to be reflected in the documentation, e.g. "Required when I(state=present)."
60 
+    * Mutually exclusive options must be documented as the final sentence on each of the options.
61 
+  * ``required:``
62 
+    Only needed if true, otherwise it is assumed to be false.
63 
+  * ``default:``
64 
+
65 
+    * If `required` is false/missing, `default` may be specified (assumed 'null' if missing).
66 
+    * Ensure that the default parameter in the docs matches the default parameter in the code.
67 
+    * The default option must not be listed as part of the description.
68 
+  * ``choices:``
69 
+    List of option values. Should be absent if empty.
70 
+  * ``aliases:``
71 
+    List of option name aliases; generally not needed.
72 
+  * ``version_added:``
73 
+    Only needed if this option was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
74 
+    This is a string, and not a float, i.e. ``version_added: "2.3"``.
75 
+* ``requirements:``
76 
+    List of requirements, and minimum versions (if applicable)
77 
+* ``notes:``
78 
+    Details of any important information that doesn't fit in one of the above sections; for example if ``check_mode`` isn't supported, or a link to external documentation.
79 
+
80 
+
81 
+
82 
+
83 
+EXAMPLES block
84 
+''''''''''''''
85 
+
86 
+The EXAMPLES section is required for all new modules.
87 
+
88 
+Examples should demonstrate real world usage, and be written in multi-line plain-text YAML format.
89 
+
90 
+Ensure that examples are kept in sync with the options during the PR review and any following code refactor.
91 
+
92 
+As per playbook best practice, a `name:` should be specified.
39 93
40 
-Examples should be written in YAML format in plain text in an
41 94 
 ``EXAMPLES`` string within the module like this::
42 95
43 96 
     EXAMPLES = '''
44 
-    - modulename:
45 
-        opt1: arg1
46 
-        opt2: arg2
97 
+    - name: Ensure foo is installed
98 
+      modulename:
99 
+        name: foo
100 
+        state: present
47 101 
     '''
48 102
49 
-The EXAMPLES section, just like the documentation section, is required in
50 
-all module pull requests for new modules.
103 
+If the module returns facts that are often needed, an example of how to use them can be helpful.
104 
+
105 
+RETURN Block
106 
+''''''''''''
107 
+
108 
+The RETURN section documents what the module returns, and is required for all new modules.
51 109
52 
-The RETURN section documents what the module returns. For each value returned,
53 
-provide a ``description``, in what circumstances the value is ``returned``,
54 
-the ``type`` of the value and a ``sample``.  For example, from
55 
-the ``copy`` module::
110 
+For each value returned, provide a ``description``, in what circumstances the value is ``returned``,
111 
+the ``type`` of the value and a ``sample``.  For example, from the ``copy`` module::
56 112
57 113 
     RETURN = '''
58 114 
     dest:
... ... 
@@ -73,19 +130,50 @@ the ``copy`` module::
73 73 
     ...
74 74 
     '''
75 75
76 
-Building & Testing
76 
+Formatting options
77 77 
 ''''''''''''''''''
78 
+These formatting functions are ``U()`` for URLs, ``I()`` for option names, ``C()`` for files and option values and ``M()`` for module names.
79 
+Module names should be specified as ``M(module)`` to create a link to the online documentation for that module.
78 80
79 
-Put your completed module file into the 'library' directory and then
81 
+
82 
+Example usage::
83 
+
84 
+    Or if not set the environment variable C(ACME_PASSWORD) will be used.
85 
+    ...
86 
+    Required if I(state=present)
87 
+    ...
88 
+    Mutually exclusive with I(project_src) and I(files).
89 
+    ...
90 
+    See also M(win_copy) or M(win_template).
91 
+    ...
92 
+    See U(https://www.ansible.com/tower) for an overview.
93 
+
94 
+
95 
+.. note::
96 
+
97 
+  If you wish to refer a collection of modules, use ``C(..)``, e.g. ``Refer to the C(win_*) modules.``
98 
+
99 
+Documentation fragments
100 
+```````````````````````
101 
+
102 
+Some categories of modules share common documentation, such as details on how to authenticate options, or file mode settings. Rather than duplicate that information it can be shared using ``docs_fragments``.
103 
+
104 
+These shared fragments are similar to the standard documentation block used in a module, they are just contained in a ``ModuleDocFragment`` class.
105 
+
106 
+All the existing ``docs_fragments`` can be found in ``lib/ansible/utils/module_docs_fragments/``.
107 
+
108 
+To include, simply add in ``extends_documentation_fragment: FRAGMENT_NAME`` into your module.
109 
+
110 
+Examples can be found by searching for ``extends_documentation_fragment`` under the Ansible source tree.
111 
+
112 
+Testing documentation
113 
+'''''''''''''''''''''
114 
+
115 
+Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` directory and then
80 116 
 run the command: ``make webdocs``. The new 'modules.html' file will be
81 
-built and appear in the 'docsite/' directory.
117 
+built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory.
82 118
83 119 
 .. tip::
84 120
85 121 
    If you're having a problem with the syntax of your YAML you can
86 122 
    validate it on the `YAML Lint <http://www.yamllint.com/>`_ website.
87 
-
88 
-.. tip::
89 
-
90 
-    You can set the environment variable ANSIBLE_KEEP_REMOTE_FILES=1 on the controlling host to prevent ansible from
91 
-    deleting the remote files so you can debug your module.
examples/DOCUMENTATION.yml
History View file @ 959637f
... ... 
@@ -2,29 +2,33 @@
2 2 
 # If a key doesn't apply to your module (ex: choices, default, or
3 3 
 # aliases) you can use the word 'null', or an empty list, [], where
4 4 
 # appropriate.
5 
+#
6 
+# See docs.ansible.com/ansible/dev_guide/developing_modules.html for more information
7 
+#
5 8 
 module: modulename
6 9 
 short_description: This is a sentence describing the module
7 10 
 description:
8 
-    - Longer description of the module
9 
-    - You might include instructions
11 
+    - Longer description of the module.
12 
+    - You might include instructions.
10 13 
 version_added: "X.Y"
11 
-author: "Your AWESOME name, @awesome-github-id"
12 
-notes:
13 
-    - Other things consumers of your module should know
14 
-    - Additional setting requirements
15 
-requirements:
16 
-    - list of required things
17 
-    - like the factor package
18 
-    - or a specific platform
14 
+author: "Your AWESOME name (@awesome-github-id)"
19 15 
 options:
20 16 
 # One or more of the following
21 17 
     option_name:
22 18 
         description:
23 
-            - Words go here
24 
-            - that describe
25 
-            - this option
19 
+            - Description of the options goes here.
20 
+            - Must be written in sentences.
26 21 
         required: true or false
27 22 
         default: a string or the word null
28 
-        choices: [list, of, choices]
29 
-        aliases: [list, of, aliases]
30 
-        version_added: 1.X
23 
+        choices:
24 
+          - enable
25 
+          - disable
26 
+        aliases:
27 
+          - repo_name
28 
+        version_added: "1.X"
29 
+notes:
30 
+    - Other things consumers of your module should know.
31 
+requirements:
32 
+    - list of required things.
33 
+    - like the factor package
34 
+    - zypper >= 1.0