Use new sphinx roles in docs

Change-Id: I92ce6b2f137f5dcb6fdee70c101c6b9d8ad5eb11
Depends-On: I9d72d11bfdb700037a6a08f92a2dbfa95ee519ad

roles/add-build-sshkey/README.rst

@@ -7,7 +7,8 @@ removes all keys from this job's SSH agent so that the original key
 used to log into all of the hosts is no longer accessible, then adds
 the newly generated private key.
 
-Role Variables
+**Role Variables**
 
-zuul_temp_ssh_key
+.. zuul:rolevar:: zuul_temp_ssh_key
-  Where to put the newly-generated SSH private key.
+
+   Where to put the newly-generated SSH private key.

roles/bindep/README.rst

@@ -5,22 +5,28 @@ that a ``other-requirements.txt``. If one exists, run ``bindep`` on the
 file to produce a list of required distro packages that do not exist and
 then install the missing packages.
 
-Role Variables
+**Role Variables**
 
-bindep_dir
+.. zuul:rolevar:: bindep_dir
-  The directory to look for bindep files in. Defaults to current directory.
+   :default: .
 
-bindep_profile
+   The directory to look for bindep files in.
-  A specific bindep profile to request. Defaults to empty.
 
-bindep_file
+.. zuul:rolevar:: bindep_profile
-  Path to a specific bindep file to read from.
 
-bindep_command
+   A specific bindep profile to request.
-  Path to the bindep command. Defaults to unset which will look for a system
-  installed bindep. If bindep_command is not found, bindep will be installed
-  into a temporary virtualenv.
 
-bindep_fallback
+.. zuul:rolevar:: bindep_file
-  Path to a bindep fallback file to be used if no bindep file can be found in
+
-  `bindep_dir`.
+   Path to a specific bindep file to read from.
+
+.. zuul:rolevar:: bindep_command
+
+   Path to the bindep command. Defaults to unset which will look for a
+   system installed bindep. If bindep_command is not found, bindep
+   will be installed into a temporary virtualenv.
+
+.. zuul:rolevar:: bindep_fallback
+
+   Path to a bindep fallback file to be used if no bindep file can be
+   found in :zuul:rolevar:`bindep.bindep_dir`.

roles/configure-mirrors/README.rst

@@ -1,9 +1,12 @@
 An ansible role to configure services to use mirrors.
 
-Role Variables
+**Role Variables**
 
-mirror_fqdn
+.. zuul:rolevar:: mirror_fqdn
-  The base host for mirror servers
 
-pypi_mirror
+   The base host for mirror servers.
-  URL to override the generated pypi mirror url based on mirror_fqdn
+
+.. zuul:rolevar:: pypi_mirror
+
+   URL to override the generated pypi mirror url based on
+   :zuul:rolevar:`configure-mirrors.mirror_fqdn`.

roles/remove-build-sshkey/README.rst

@@ -1,9 +1,10 @@
 Remove the per-build SSH key from all hosts
 
-The complement to `add-build-sshkey`.  It removes the build's SSH key
+The complement to :zuul:role:`add-build-sshkey`.  It removes the
-from the authorized_keys files of all remote hosts.
+build's SSH key from the authorized_keys files of all remote hosts.
 
-Role Variables
+**Role Variables**
 
-zuul_temp_ssh_key
+.. zuul:rolevar:: zuul_temp_ssh_key
-  Where the per-build SSH private key was stored.
+
+   Where the per-build SSH private key was stored.

roles/tox/README.rst

@@ -1,23 +1,33 @@
-Runs tox for a project.
+Runs tox for a project
 
-Role Variables
+**Role Variables**
 
-tox_environment
+.. zuul:rolevar:: tox_environment
-  Environment variables to pass in to the tox run.
 
-tox_environment_defaults
+   Environment variables to pass in to the tox run.
-  Default environment variables to pass in to the tox run. Intended to allow
-  setting a set of environment variables in a base job but to still allow
-  specific settings on a per-job or per-variant basis.
 
-tox_envlist
+.. zuul:rolevar:: tox_environment_defaults
-  Which tox environment to run. Defaults to 'venv'.
 
-tox_executable
+   Default environment variables to pass in to the tox run. Intended
-  Location of the tox executable. Defaults to 'tox'.
+   to allow setting a set of environment variables in a base job but
+   to still allow specific settings on a per-job or per-variant basis.
 
-tox_extra_args
+.. zuul:rolevar:: tox_envlist
-  String of extra command line options to pass to tox. Defaults to '-vv'.
+   :default: venv
 
-zuul_work_dir
+   Which tox environment to run.
-  Directory to run tox in.
+
+.. zuul:rolevar:: tox_executable
+   :default: tox
+
+   Location of the tox executable.
+
+.. zuul:rolevar:: tox_extra_args
+   :default: -vv
+
+   String of extra command line options to pass to tox.
+
+.. zuul:rolevar:: zuul_work_dir
+   :default: src/{{ zuul.project.canonical_name }}
+
+   Directory to run tox in.

roles/upload-logs/README.rst

@@ -2,7 +2,9 @@ Upload logs to a static webserver
 
 This uploads logs to a static webserver using SSH.
 
-Role Variables
+**Role Variables**
 
-zuul_logserver_root
+.. zuul:rolevar:: zuul_logserver_root
-  The root path to the logs on the logserver.
+   :default: /srv/static/logs
+
+   The root path to the logs on the logserver.

zuul.yaml

@@ -21,14 +21,18 @@
 
       Responds to these variables:
 
-      tox_envlist
+      .. zuul:jobvar:: tox_envlist
-        work against specified environments (ALL selects all)
 
-      tox_environment
+         Use the specified tox environments (``ALL`` selects all).
-        list of user defined environmental variables to pass to bash shell
 
-      tox_command_line
+      .. zuul:jobvar:: tox_environment
-        an optional command line
+
+         List of user defined environmental variables to pass to bash
+         shell.
+
+      .. zuul:jobvar:: tox_command_line
+
+         An optional command line.
     run: playbooks/tox/run
     pre-run: playbooks/tox/pre
     post-run: playbooks/tox/post
@@ -44,7 +48,7 @@
     description: |
       Run unit tests for a Python project under cPython version 2.7.
 
-      Uses tox with the "py27" environment.
+      Uses tox with the ``py27`` environment.
     vars:
       tox_envlist: py27
 
@@ -54,7 +58,7 @@
     description: |
       Run unit tests for a Python project under cPython version 3.4.
 
-      Uses tox with the "py34" environment.
+      Uses tox with the ``py34`` environment.
     vars:
       tox_envlist: py34
 
@@ -64,7 +68,7 @@
     description: |
       Run unit tests for a Python project under cPython version 3.5.
 
-      Uses tox with the "py35" environment.
+      Uses tox with the ``py35`` environment.
     vars:
       tox_envlist: py35
 
@@ -77,7 +81,7 @@
     description: |
       Run documentation unit tests.
 
-      Uses tox with the "docs" environment.
+      Uses tox with the ``docs`` environment.
     vars:
       tox_envlist: docs
     post-run: playbooks/tox/docs-post
@@ -89,7 +93,7 @@
     description: |
       Runs code linting tests.
 
-      Uses tox with the "linters" environment.
+      Uses tox with the ``linters`` environment.
     vars:
       tox_envlist: linters
 
@@ -99,7 +103,7 @@
     description: |
       Runs code pep8 tests.
 
-      Uses tox with the "pep8" environment.
+      Uses tox with the ``pep8`` environment.
     vars:
       tox_envlist: pep8
 
@@ -109,7 +113,7 @@
     description: |
       Run code coverage tests.
 
-      Uses tox with the "cover" environment.
+      Uses tox with the ``cover`` environment.
     vars:
       tox_envlist: cover
 
@@ -119,7 +123,7 @@
     description: |
       Generate a python source tarball and a binary wheel
 
-      Uses tox with the "venv" environment.
+      Uses tox with the ``venv`` environment.
     vars:
       tox_envlist: venv
     run: playbooks/tox/tarball