Docs: add a :default: argument to zuul:attr

This lets us specify the default as part of the "signature" for
each of the attributes.  This helps standardize information about
default values and avoid needing to incorporate it into the text
description of each attribute.

Standardize on lowercase representation of booleans.

Change-Id: I4892b579545dd459fa877feb3014c4c4f2ced2eb

2 files changed, 58 insertions, 28 deletions

diff --git a/doc/source/user/config.rst b/doc/source/user/config.rst
index 6d2fda483..b86741e9d 100644
--- a/doc/source/user/config.rst
+++ b/doc/source/user/config.rst
@@ -184,14 +184,16 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
          dependent pipeline manager, see: :doc:`gating`.
 
    .. attr:: allow-secrets
+      :default: false
 
       This is a boolean which can be used to prevent jobs which
       require secrets from running in this pipeline.  Some pipelines
       run on proposed changes and therefore execute code which has not
       yet been reviewed.  In such a case, allowing a job to use a
       secret could result in that secret being exposed.  The default
-      is False, meaning that in order to run jobs with secrets, this
-      must be explicitly enabled on each Pipeline where that is safe.
+      is ``false``, meaning that in order to run jobs with secrets,
+      this must be explicitly enabled on each Pipeline where that is
+      safe.
 
       For more information, see :ref:`secret`.
 
@@ -201,16 +203,19 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       pipeline.  It may appear in the status page or in documentation.
 
    .. attr:: success-message
+      :default: Build successful.
 
       The introductory text in reports when all the voting jobs are
-      successful.  Defaults to "Build successful."
+      successful.
 
    .. attr:: failure-message
+      :default: Build failed.
 
       The introductory text in reports when at least one voting job
-      fails.  Defaults to "Build failed."
+      fails.
 
    .. attr:: merge-failure-message
+      :default: Merge failed.
 
       The introductory text in the message reported when a change
       fails to merge with the current state of the repository.
@@ -257,14 +262,16 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       See :ref:`drivers`.
 
    .. attr:: dequeue-on-new-patchset
+      :default: true
 
       Normally, if a new patchset is uploaded to a change that is in a
       pipeline, the existing entry in the pipeline will be removed
       (with jobs canceled and any dependent changes that can no longer
       merge as well.  To suppress this behavior (and allow jobs to
-      continue running), set this to ``false``.  Default: ``true``.
+      continue running), set this to ``false``.
 
    .. attr:: ignore-dependencies
+      :default: false
 
       In any kind of pipeline (dependent or independent), Zuul will
       attempt to enqueue all dependencies ahead of the current change
@@ -272,9 +279,10 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       the results of each change regardless of the results of changes
       ahead).  To ignore dependencies completely in an independent
       pipeline, set this to ``true``.  This option is ignored by
-      dependent pipelines.  The default is: ``false``.
+      dependent pipelines.
 
    .. attr:: precedence
+      :default: normal
 
       Indicates how the build scheduler should prioritize jobs for
       different pipelines.  Each pipeline may have one precedence,
@@ -340,6 +348,7 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       pipeline is disabled).
 
    .. attr:: window
+      :default: 20
 
       Dependent pipeline managers only. Zuul can rate limit dependent
       pipelines in a manner similar to TCP flow control.  Jobs are
@@ -348,15 +357,17 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       window is configurable with this value. The value given should
       be a positive integer value. A value of ``0`` disables rate
       limiting on the :value:`dependent pipeline manager
-      <pipeline.manager.dependent>`.  Default: ``20``.
+      <pipeline.manager.dependent>`.
 
    .. attr:: window-floor
+      :default: 3
 
       Dependent pipeline managers only. This is the minimum value for
       the window described above. Should be a positive non zero
-      integer value.  Default: ``3``.
+      integer value.
 
    .. attr:: window-increase-type
+      :default: linear
 
       Dependent pipeline managers only. This value describes how the
       window should grow when changes are successfully merged by zuul.
@@ -364,7 +375,7 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
       .. value:: linear
 
          Indicates that **window-increase-factor** should be added to
-         the previous window value.  This is the default.
+         the previous window value.
 
       .. value:: exponential
 
@@ -373,12 +384,14 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
          will become the window size.
 
    .. attr:: window-increase-factor
+      :default: 1
 
       Dependent pipeline managers only. The value to be added or
       multiplied against the previous window value to determine the
-      new window after successful change merges.  Default: ``1``.
+      new window after successful change merges.
 
    .. attr:: window-decrease-type
+      :default: exponential
 
       Dependent pipeline managers only. This value describes how the
       window should shrink when changes are not able to be merged by
@@ -393,14 +406,15 @@ success, the pipeline reports back to Gerrit with ``Verified`` vote of
 
          Indicates that **window-decrease-factor** should be divided
          against the previous window value and the result will become
-         the window size.  This is the default.
+         the window size.
 
    .. attr:: window-decrease-factor
+      :default: 2
 
       :value:`Dependent pipeline managers
       <pipeline.manager.dependent>` only. The value to be subtracted
       or divided against the previous window value to determine the
-      new window after unsuccessful change merges.  Default: ``2``.
+      new window after unsuccessful change merges.
 
 
 .. _job:
@@ -503,16 +517,18 @@ Here is an example of two job definitions:
       ReStructuredText.
 
    .. attr:: success-message
+      :default: SUCCESS
 
       Normally when a job succeeds, the string ``SUCCESS`` is reported
       as the result for the job.  If set, this option may be used to
-      supply a different string.  Default: ``SUCCESS``.
+      supply a different string.
 
    .. attr:: failure-message
+      :default: FAILURE
 
       Normally when a job fails, the string ``FAILURE`` is reported as
       the result for the job.  If set, this option may be used to
-      supply a different string.  Default: ``FAILURE``.
+      supply a different string.
 
    .. attr:: success-url
 
@@ -526,7 +542,7 @@ Here is an example of two job definitions:
       **zuul.log_url** is set, then the two will be combined to
       produce the URL used for the report.  This can be used to
       specify that certain jobs should "deep link" into the stored job
-      artifacts.  Default: none.
+      artifacts.
 
    .. attr:: failure-url
 
@@ -534,26 +550,27 @@ Here is an example of two job definitions:
       Otherwise behaves the same as **success-url**.
 
    .. attr:: hold-following-changes
+      :default: false
 
       In a dependent pipeline, this option may be used to indicate
       that no jobs should start on any items which depend on the
       current item until this job has completed successfully.  This
       may be used to conserve build resources, at the expense of
       inhibiting the parallelization which speeds the processing of
-      items in a dependent pipeline.  A boolean value, default: false.
+      items in a dependent pipeline.
 
    .. attr:: voting
+      :default: true
 
       Indicates whether the result of this job should be used in
-      determining the overall result of the item.  A boolean value,
-      default: true.
+      determining the overall result of the item.
 
    .. attr:: semaphore
 
       The name of a :ref:`semaphore` which should be acquired and
       released when the job begins and ends.  If the semaphore is at
       maximum capacity, then Zuul will wait until it can be acquired
-      before starting the job.  Default: none.
+      before starting the job.
 
    .. attr:: tags
 
@@ -567,7 +584,7 @@ Here is an example of two job definitions:
       strings, and when inheriting jobs or applying variants, tags
       accumulate in a set, so the result is always a set of all the
       tags from all the jobs and variants used in constructing the
-      frozen job, with no duplication.  Default: none.
+      frozen job, with no duplication.
 
    .. attr:: branches
 
@@ -626,7 +643,7 @@ Here is an example of two job definitions:
 
       This attribute indicates that the job should only run on changes
       where the specified files are modified.  This is a regular
-      expression or list of regular expressions.  Default: none.
+      expression or list of regular expressions.
 
    .. attr:: irrelevant-files
 
@@ -635,7 +652,7 @@ Here is an example of two job definitions:
       list.  In other words, if the regular expression ``docs/.*`` is
       supplied, then this job will not run if the only files changed
       are in the docs directory.  A regular expression or list of
-      regular expressions.  Default: none.
+      regular expressions.
 
    .. attr:: auth
 
@@ -643,6 +660,7 @@ Here is an example of two job definitions:
       This is a dictionary with two potential keys:
 
       .. attr:: inherit
+         :default: false
 
          A boolean indicating that the authentication information
          referenced by this job should be able to be inherited by
@@ -652,7 +670,7 @@ Here is an example of two job definitions:
          that secret information is unable to be exposed by a child
          job which may alter the job's behavior.  If it is safe for
          the contents of the authentication section to be used by
-         child jobs, set this to ``true``.  Default: ``false``.
+         child jobs, set this to ``true``.
 
       .. attr:: secrets
 
@@ -704,13 +722,14 @@ Here is an example of two job definitions:
       timeout is highly recommended.
 
    .. attr:: attempts
+      :default: 3
 
       When Zuul encounters an error running a job's pre-run playbook,
       Zuul will stop and restart the job.  Errors during the main or
       post-run -playbook phase of a job are not affected by this
       parameter (they are reported immediately).  This parameter
       controls the number of attempts to make before an error is
-      reported.  Default: ``3``.
+      reported.
 
    .. attr:: pre-run
 
@@ -873,7 +892,7 @@ Here is an example of two job definitions:
       all projects permitted to use the job.  The current project
       (where the job is defined) is not automatically included, so if
       it should be able to run this job, then it must be explicitly
-      listed.  Default: the empty list (all projects may use the job).
+      listed.  By default, all projects may use the job.
 
 
 .. _project:
diff --git a/zuul/sphinx/zuul.py b/zuul/sphinx/zuul.py
index 779872024..b4133d7e1 100644
--- a/zuul/sphinx/zuul.py
+++ b/zuul/sphinx/zuul.py
@@ -75,6 +75,7 @@ class ZuulAttrDirective(ZuulConfigObject):
 
     option_spec = {
         'required': lambda x: x,
+        'default': lambda x: x,
     }
 
     def before_content(self):
@@ -88,11 +89,21 @@ class ZuulAttrDirective(ZuulConfigObject):
 
     def handle_signature(self, sig, signode):
         path = self.get_path()
+        signode['is_multiline'] = True
+        line = addnodes.desc_signature_line()
+        line['add_permalink'] = True
         for x in path:
-            signode += addnodes.desc_addname(x + '.', x + '.')
-        signode += addnodes.desc_name(sig, sig)
+            line += addnodes.desc_addname(x + '.', x + '.')
+        line += addnodes.desc_name(sig, sig)
         if 'required' in self.options:
-            signode += addnodes.desc_annotation(' (required)', ' (required)')
+            line += addnodes.desc_annotation(' (required)', ' (required)')
+        signode += line
+        if 'default' in self.options:
+            line = addnodes.desc_signature_line()
+            line += addnodes.desc_type('Default: ', 'Default: ')
+            line += nodes.literal(self.options['default'],
+                                  self.options['default'])
+            signode += line
         return sig