From 912f9761559a12aa31accf1cf4d5e5f93bc94ca3 Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Fri, 11 Aug 2017 15:10:40 -0700 Subject: [PATCH] Use new sphinx roles in docs Change-Id: I92ce6b2f137f5dcb6fdee70c101c6b9d8ad5eb11 Depends-On: I9d72d11bfdb700037a6a08f92a2dbfa95ee519ad --- roles/add-build-sshkey/README.rst | 7 +++-- roles/bindep/README.rst | 34 ++++++++++++---------- roles/configure-mirrors/README.rst | 13 +++++---- roles/remove-build-sshkey/README.rst | 11 ++++---- roles/tox/README.rst | 42 +++++++++++++++++----------- roles/upload-logs/README.rst | 8 ++++-- zuul.yaml | 32 +++++++++++---------- 7 files changed, 87 insertions(+), 60 deletions(-) diff --git a/roles/add-build-sshkey/README.rst b/roles/add-build-sshkey/README.rst index 995a48b14..d2b5527f9 100644 --- a/roles/add-build-sshkey/README.rst +++ b/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 - Where to put the newly-generated SSH private key. +.. zuul:rolevar:: zuul_temp_ssh_key + + Where to put the newly-generated SSH private key. diff --git a/roles/bindep/README.rst b/roles/bindep/README.rst index 0bd617535..84dc655e3 100644 --- a/roles/bindep/README.rst +++ b/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 - The directory to look for bindep files in. Defaults to current directory. +.. zuul:rolevar:: bindep_dir + :default: . -bindep_profile - A specific bindep profile to request. Defaults to empty. + The directory to look for bindep files in. -bindep_file - Path to a specific bindep file to read from. +.. zuul:rolevar:: bindep_profile -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. + A specific bindep profile to request. -bindep_fallback - Path to a bindep fallback file to be used if no bindep file can be found in - `bindep_dir`. +.. zuul:rolevar:: bindep_file + + 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`. diff --git a/roles/configure-mirrors/README.rst b/roles/configure-mirrors/README.rst index b7c1fe93a..40f3d62fa 100644 --- a/roles/configure-mirrors/README.rst +++ b/roles/configure-mirrors/README.rst @@ -1,9 +1,12 @@ An ansible role to configure services to use mirrors. -Role Variables +**Role Variables** -mirror_fqdn - The base host for mirror servers +.. zuul:rolevar:: mirror_fqdn -pypi_mirror - URL to override the generated pypi mirror url based on mirror_fqdn + The base host for mirror servers. + +.. zuul:rolevar:: pypi_mirror + + URL to override the generated pypi mirror url based on + :zuul:rolevar:`configure-mirrors.mirror_fqdn`. diff --git a/roles/remove-build-sshkey/README.rst b/roles/remove-build-sshkey/README.rst index a06fb27c2..d046ac44a 100644 --- a/roles/remove-build-sshkey/README.rst +++ b/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 -from the authorized_keys files of all remote hosts. +The complement to :zuul:role:`add-build-sshkey`. It removes the +build's SSH key from the authorized_keys files of all remote hosts. -Role Variables +**Role Variables** -zuul_temp_ssh_key - Where the per-build SSH private key was stored. +.. zuul:rolevar:: zuul_temp_ssh_key + + Where the per-build SSH private key was stored. diff --git a/roles/tox/README.rst b/roles/tox/README.rst index 9c50a8df0..45fa89abf 100644 --- a/roles/tox/README.rst +++ b/roles/tox/README.rst @@ -1,23 +1,33 @@ -Runs tox for a project. +Runs tox for a project -Role Variables +**Role Variables** -tox_environment - Environment variables to pass in to the tox run. +.. zuul:rolevar:: tox_environment -tox_environment_defaults - 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. + Environment variables to pass in to the tox run. -tox_envlist - Which tox environment to run. Defaults to 'venv'. +.. zuul:rolevar:: tox_environment_defaults -tox_executable - Location of the tox executable. Defaults to 'tox'. + 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_extra_args - String of extra command line options to pass to tox. Defaults to '-vv'. +.. zuul:rolevar:: tox_envlist + :default: venv -zuul_work_dir - Directory to run tox in. + Which tox environment to run. + +.. 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. diff --git a/roles/upload-logs/README.rst b/roles/upload-logs/README.rst index c6491ae0e..969d07cf9 100644 --- a/roles/upload-logs/README.rst +++ b/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 - The root path to the logs on the logserver. +.. zuul:rolevar:: zuul_logserver_root + :default: /srv/static/logs + + The root path to the logs on the logserver. diff --git a/zuul.yaml b/zuul.yaml index ced8e434a..f1ae6a25c 100644 --- a/zuul.yaml +++ b/zuul.yaml @@ -21,14 +21,18 @@ Responds to these variables: - tox_envlist - work against specified environments (ALL selects all) + .. zuul:jobvar:: tox_envlist - tox_environment - list of user defined environmental variables to pass to bash shell + Use the specified tox environments (``ALL`` selects all). - tox_command_line - an optional command line + .. zuul:jobvar:: tox_environment + + 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