No module should be considered complete unless it contains documentation regarding how to operate it. Documentation for a module exists within the module itself, in special variables called DOCUMENTATION, EXAMPLES, and RETURN.

The DOCUMENTATION variable contains a specially formatted string describing the module name, the version that was added to Ansible (if it is in Ansible proper), a short description of the module, a longer description, a description of the module arguments, author and license information, additional requirements, and any extra notes useful to users of the module. Let's add a DOCUMENTATION string to our module under the existing import shutil statement:

import shutil 
 
DOCUMENTATION = ''' 
--- 
module: remote_copy 
version_added: future 
short_description: Copy a file on the remote host 
description: 
  - The remote_copy module copies a file on the remote host from a given source to a provided destination. 
options: 
  source: 
    description: 
      - Path to a file on the source file on the remote host 
    required: True 
  dest: 
    description: 
      - Path to the destination on the remote host for the copy 
    required: True 
author: 
  - Jesse Keating 
''' 

The format of the string is essentially YAML, with some top-level keys containing hash structures within it (the same as the options key). Each option has sub-elements to describe the option, indicate whether the option is required, list any aliases for the option, list static choices for the option, or indicate a default value for the option. With this string saved to the module, we can test our formatting to ensure that the documentation will render correctly. This is done via the ansible-doc tool, with an argument to indicate where to search for the modules. If we run it from the same place as our playbook, the command will be ansible-doc -M library/ remote_copy, and the output will be as follows:

In this example, I've piped the output into cat to prevent the pager from hiding the execution line. Our documentation string appears to be formatted correctly and provides the user with important information regarding the usage of the module.

The EXAMPLES string is used to provide one or more example uses of the module, snippets of the task code that you would use in a playbook. Let's add an example task to demonstrate the usage. This variable definition traditionally goes after the DOCUMENTATION definition:

EXAMPLES = ''' 
# Example from Ansible Playbooks 
- name: backup a config file 
  remote_copy: 
    source: /etc/herp/derp.conf 
    dest: /root/herp-derp.conf.bak 
''' 

With this variable defined, our ansible-doc output will now include the example, as we can see in the following screenshot:

The last documentation variable, RETURN, is a relatively new feature of module documentation. This variable is used to describe the return data from a module execution. Return data is often useful as a registered variable for later usage, and having documentation of what return data to expect can aid playbook development. Our module doesn't have any return data yet; so, before we can document any some, we first have to add return data. This can be done by modifying the module.exit_json line to add more information. Let's add the source and dest data to the return output:

    module.exit_json(changed=True, source=module.params['source'], 
                     dest=module.params['dest']) 

Rerunning the playbook will show extra data being returned, as shown in the following screenshot:

Looking closely at the return data, we can see more data than we put in our module. This is actually a bit of a helper functionality within Ansible; when a return dataset includes a dest variable, Ansible will gather more information about the destination file. The extra data gathered is gid (group ID), group (group name), mode (permissions), uid (owner ID), owner (owner name), size, and state (file, link, or directory). We can document all of these return items in our RETURN variable, which is added after the EXAMPLES variable. Everything between the two sets of single quotes (''') is returned – thus, this first part returns the file paths and ownership:

RETURN = ''' 
source: 
  description: source file used for the copy 
  returned: success 
  type: string 
  sample: "/path/to/file.name" 
dest: 
  description: destination of the copy 
  returned: success 
  type: string 
  sample: "/path/to/destination.file" 
gid: 
  description: group ID of destination target 
  returned: success 
  type: int 
  sample: 502 
group: 
  description: group name of destination target 
  returned: success 
  type: string 
  sample: "users" 
uid: 
  description: owner ID of destination target 
  returned: success 
  type: int 
  sample: 502 
owner: 
  description: owner name of destination target 
  returned: success 
  type: string 
  sample: "fred"

Continuing this part of the module definition file, this section returns the details about the file size, state, and permissions:

mode: 
  description: permissions of the destination target 
  returned: success 
  type: int 
  sample: 0644 
size: 
  description: size of destination target 
  returned: success 
  type: int 
  sample: 20 
state: 
  description: state of destination target 
  returned: success 
  type: string 
  sample: "file" 
''' 

Each returned item is listed with a description, the cases when the item would be in the return data, the type of item it is, and a sample of the value. The RETURN string is essentially repeated verbatim in the ansible-doc output, as shown in the following (abbreviated) example:

In this way, we have built up a module that contains its own documentation – incredibly useful for others if we are contributing it to the community, or even for ourselves when we come back to it after a period of time.