This role does some awesome stuff!

The following documentation contains examples for different variable types
and how they can be documented properly using the zuul specific Sphinx
directives.

**Role variables**

.. zuul:rolevar:: mandatory_variable

   This is just a simple variable that must be set when using the role.

.. zuul:rolevar:: optional_variable
   :default: True

   This variable is optional. If not set, its default value will be used.

.. zuul:rolevar:: list_variable
   :default: []
   :type: list

   This variable must be a list. If not set, an empty list will be used.
   This syntax should be used for simple lists containing simple elements
   like Strings, Bools or Numbers.

.. zuul:rolevar:: complex_list
   :type: list

   If the list contains more complex items, it can be documented like this
   one. Take a look at the intendation.

   .. zuul:rolevar:: item
      :type: dict

      This shows how a single list item should look like. In the rendered
      documentation file, this list item will be namespaced accordingly to
      state out, that it belongs to the complex_list variable.

      .. zuul:rolevar:: message

         Every list item must have a message.

      .. zuul:rolevar:: timestamp
         :default: <current_time>

         The timestamp is optional. If not set, the role will use the current
         timestamp.

.. zuul:rolevar:: dict_variable
   :type: dict

   This variable must be a dictionary. As it does not provide any default
   value and thus, must be set to use this role.