docs: improve job.role documentation

- Adds usage example for using role inside jobs before the long detailed
  explanation in order to avoid need to scroll to see it. Also very
  useful if someone shares a link to that section
- Transforms the not implemented galaxy notice into a warning and moves
  it inside the galaxy section in order to avoid confusions. The
  previous layout confused at least two people reading the roles section.

Change-Id: If52af6304cc1467d63ca54f5192f3004631023a3

doc/source/reference/job_def.rst

@@ -505,6 +505,16 @@ Here is an example of two job definitions:
 
    .. attr:: roles
 
+      .. code-block:: yaml
+         :name: job-roles-example
+
+         - job:
+             name: myjob
+             roles:
+               - zuul: myorg/our-roles-project
+               - zuul: myorg/ansible-role-foo
+                 name: foo
+
       A list of Ansible roles to prepare for the job.  Because a job
       runs an Ansible playbook, any roles which are used by the job
       must be prepared and installed by Zuul before the job begins.
@@ -559,10 +569,10 @@ Here is an example of two job definitions:
       explicitly listing the project in the roles list in the usual
       way.
 
-      .. note:: Galaxy roles are not yet implemented.
-
       .. attr:: galaxy
 
+         .. warning:: Galaxy roles are not yet implemented.
+
          The name of the role in Ansible Galaxy.  If this attribute is
          supplied, Zuul will search Ansible Galaxy for a role by this
          name and install it.  Mutually exclusive with ``zuul``;