Cleanup components doc
This will:
1) Make the config examples more prominent in the rendered document.
They currently jumble into the descriptive text, making them
difficult to distinquish.
2) Remove the use of "Optional" in the descriptive text. Every option
should be considered optional by default (and we didn't even use it
consistently) and we should simply just point out the *required*
options instead.
Change-Id: I1e7d559b7a1f36c9dca2f188e849f0674bd71378
diff --git a/doc/source/admin/components.rst b/doc/source/admin/components.rst
index 26a85b2..a0de922 100644
--- a/doc/source/admin/components.rst
+++ b/doc/source/admin/components.rst
@@ -32,24 +32,25 @@
Client connection information for gearman.
-**server**
- Hostname or IP address of the Gearman server.
- ``server=gearman.example.com`` (required)
+**server** (required)
+ Hostname or IP address of the Gearman server::
+
+ server=gearman.example.com
**port**
- Port on which the Gearman server is listening.
- ``port=4730`` (optional)
+ Port on which the Gearman server is listening::
+
+ port=4730
**ssl_ca**
- Optional: An openssl file containing a set of concatenated
- “certification authority” certificates in PEM formet.
+ An openssl file containing a set of concatenated “certification
+ authority” certificates in PEM formet.
**ssl_cert**
- Optional: An openssl file containing the client public certificate in
- PEM format.
+ An openssl file containing the client public certificate in PEM format.
**ssl_key**
- Optional: An openssl file containing the client private key in PEM format.
+ An openssl file containing the client private key in PEM format.
zookeeper
"""""""""
@@ -60,7 +61,9 @@
**hosts**
A list of zookeeper hosts for Zuul to use when communicating with
- Nodepool. ``hosts=zk1.example.com,zk2.example.com,zk3.example.com``
+ Nodepool::
+
+ hosts=zk1.example.com,zk2.example.com,zk3.example.com
Scheduler
@@ -85,66 +88,76 @@
than connecting to an external one.
**start**
- Whether to start the internal Gearman server (default: False).
- ``start=true``
+ Whether to start the internal Gearman server (default: False)::
+
+ start=true
**listen_address**
- IP address or domain name on which to listen (default: all addresses).
- ``listen_address=127.0.0.1``
+ IP address or domain name on which to listen (default: all addresses)::
+
+ listen_address=127.0.0.1
**log_config**
- Path to log config file for internal Gearman server.
- ``log_config=/etc/zuul/gearman-logging.yaml``
+ Path to log config file for internal Gearman server::
+
+ log_config=/etc/zuul/gearman-logging.yaml
**ssl_ca**
- Optional: An openssl file containing a set of concatenated “certification authority” certificates
- in PEM formet.
+ An openssl file containing a set of concatenated “certification authority”
+ certificates in PEM formet.
**ssl_cert**
- Optional: An openssl file containing the server public certificate in PEM format.
+ An openssl file containing the server public certificate in PEM format.
**ssl_key**
- Optional: An openssl file containing the server private key in PEM format.
+ An openssl file containing the server private key in PEM format.
webapp
""""""
**listen_address**
- IP address or domain name on which to listen (default: 0.0.0.0).
- ``listen_address=127.0.0.1``
+ IP address or domain name on which to listen (default: 0.0.0.0)::
+
+ listen_address=127.0.0.1
**port**
- Port on which the webapp is listening (default: 8001).
- ``port=8008``
+ Port on which the webapp is listening (default: 8001)::
+
+ port=8008
**status_expiry**
- Zuul will cache the status.json file for this many seconds. This is an
- optional value and ``1`` is used by default.
- ``status_expiry=1``
+ Zuul will cache the status.json file for this many seconds (default: 1)::
+
+ status_expiry=1
**status_url**
URL that will be posted in Zuul comments made to changes when
- starting jobs for a change. Used by zuul-scheduler only.
- ``status_url=https://zuul.example.com/status``
+ starting jobs for a change. Used by zuul-scheduler only::
+
+ status_url=https://zuul.example.com/status
scheduler
"""""""""
**tenant_config**
- Path to tenant config file.
- ``layout_config=/etc/zuul/tenant.yaml``
+ Path to tenant config file::
+
+ layout_config=/etc/zuul/tenant.yaml
**log_config**
- Path to log config file.
- ``log_config=/etc/zuul/scheduler-logging.yaml``
+ Path to log config file::
+
+ log_config=/etc/zuul/scheduler-logging.yaml
**pidfile**
- Path to PID lock file.
- ``pidfile=/var/run/zuul/scheduler.pid``
+ Path to PID lock file::
+
+ pidfile=/var/run/zuul/scheduler.pid
**state_dir**
- Path to directory that Zuul should save state to.
- ``state_dir=/var/lib/zuul``
+ Path to directory that Zuul should save state to::
+
+ state_dir=/var/lib/zuul
Operation
~~~~~~~~~
@@ -186,24 +199,29 @@
""""""
**git_dir**
- Directory that Zuul should clone local git repositories to.
- ``git_dir=/var/lib/zuul/git``
+ Directory that Zuul should clone local git repositories to::
+
+ git_dir=/var/lib/zuul/git
**git_user_email**
- Optional: Value to pass to `git config user.email`.
- ``git_user_email=zuul@example.com``
+ Value to pass to `git config user.email`::
+
+ git_user_email=zuul@example.com
**git_user_name**
- Optional: Value to pass to `git config user.name`.
- ``git_user_name=zuul``
+ Value to pass to `git config user.name`::
+
+ git_user_name=zuul
**log_config**
- Path to log config file for the merger process.
- ``log_config=/etc/zuul/logging.yaml``
+ Path to log config file for the merger process::
+
+ log_config=/etc/zuul/logging.yaml
**pidfile**
- Path to PID lock file for the merger process.
- ``pidfile=/var/run/zuul-merger/merger.pid``
+ Path to PID lock file for the merger process::
+
+ pidfile=/var/run/zuul-merger/merger.pid
Operation
~~~~~~~~~
@@ -273,37 +291,44 @@
""""""""
**finger_port**
- Port to use for finger log streamer.
- ``finger_port=79``
+ Port to use for finger log streamer::
+
+ finger_port=79
**git_dir**
- Directory that Zuul should clone local git repositories to.
- ``git_dir=/var/lib/zuul/git``
+ Directory that Zuul should clone local git repositories to::
+
+ git_dir=/var/lib/zuul/git
**log_config**
- Path to log config file for the executor process.
- ``log_config=/etc/zuul/logging.yaml``
+ Path to log config file for the executor process::
+
+ log_config=/etc/zuul/logging.yaml
**private_key_file**
- SSH private key file to be used when logging into worker nodes.
- ``private_key_file=~/.ssh/id_rsa``
+ SSH private key file to be used when logging into worker nodes::
+
+ private_key_file=~/.ssh/id_rsa
**user**
User ID for the zuul-executor process. In normal operation as a daemon,
the executor should be started as the ``root`` user, but it will drop
- privileges to this user during startup.
- ``user=zuul``
+ privileges to this user during startup::
+
+ user=zuul
merger
""""""
**git_user_email**
- Optional: Value to pass to `git config user.email`.
- ``git_user_email=zuul@example.com``
+ Value to pass to `git config user.email`::
+
+ git_user_email=zuul@example.com
**git_user_name**
- Optional: Value to pass to `git config user.name`.
- ``git_user_name=zuul``
+ Value to pass to `git config user.name`::
+
+ git_user_name=zuul
Operation
~~~~~~~~~
@@ -341,20 +366,24 @@
"""
**listen_address**
- IP address or domain name on which to listen (default: 127.0.0.1).
- ``listen_address=127.0.0.1``
+ IP address or domain name on which to listen (default: 127.0.0.1)::
+
+ listen_address=127.0.0.1
**log_config**
- Path to log config file for the web server process.
- ``log_config=/etc/zuul/logging.yaml``
+ Path to log config file for the web server process::
+
+ log_config=/etc/zuul/logging.yaml
**pidfile**
- Path to PID lock file for the web server process.
- ``pidfile=/var/run/zuul-web/zuul-web.pid``
+ Path to PID lock file for the web server process::
+
+ pidfile=/var/run/zuul-web/zuul-web.pid
**port**
- Port to use for web server process.
- ``port=9000``
+ Port to use for web server process::
+
+ port=9000
Operation
~~~~~~~~~