Docs: add initial documentation style guide

Change-Id: Ib4b710feda98b97d484817b1fb59d5893edc3704

doc/source/developer/docs.rst

@@ -0,0 +1,220 @@
+Documentation
+=============
+
+This is a brief style guide for Zuul documentation.
+
+ReStructuredText Conventions
+----------------------------
+
+Code Blocks
+~~~~~~~~~~~
+
+When showing a YAML example, use the ``.. code-block:: yaml``
+directive so that the sample appears as a code block with the correct
+syntax highlighting.
+
+Literal Values
+~~~~~~~~~~~~~~
+
+Filenames and literal values (such as when we instruct a user to type
+a specific string into a configuration file) should use the RST
+````literal```` syntax.
+
+Terminology
+~~~~~~~~~~~
+
+Zuul employs some specialized terminology.  To help users become
+acquainted with it, we employ a glossary.  Observe the following:
+
+* Specialized terms should have entries in the glossary.
+
+* If the term is being defined in the text, don't link to the glossary
+  (that would be redundant), but do emphasize it with ``*italics*``
+  the first time it appears in that definition.  Subsequent uses
+  within the same subsection should be in regular type.
+
+* If it's being used (but not defined) in the text, link the first
+  usage within a subsection to the glossary using the ``:term:`` role,
+  but subsequent uses should be in regular type.
+
+* Be cognizant of how readers may jump to link targets within the
+  text, so be liberal in considering that once you cross a link
+  target, you may be in a new "subsection" for the above guideline.
+
+
+Zuul Sphinx Directives
+----------------------
+
+The following extra Sphinx directives are available in the ``zuul``
+domain.  The ``zuul`` domain is configured as the default domain, so the
+``zuul:`` prefix may be omitted.
+
+zuul:attr::
+~~~~~~~~~~~
+
+This should be used when documenting Zuul configuration attributes.
+Zuul configuration is heavily hierarchical, and this directive
+facilitates documenting these by emphasising the hierarchy as
+appropriate.  It will annotate each configuration attribute with a
+nice header with its own unique hyperlink target.  It displays the
+entire hierarchy of the attribute, but emphasises the last portion
+(i.e., the field being documented).
+
+To use the hierarchical features, simply nest with indendtation in the
+normal RST manner.
+
+It supports the ``required`` and ``default`` options and will annotate
+the header appropriately.  Example:
+
+.. code-block:: rst
+
+   .. attr:: foo
+
+      Some text about ``foo``.
+
+      .. attr:: bar
+         :required:
+         :default: 42
+
+         Text about ``foo.bar``.
+
+.. attr:: foo
+   :noindex:
+
+   Some text about ``foo``.
+
+   .. attr:: bar
+      :noindex:
+      :required:
+      :default: 42
+
+      Text about ``foo.bar``.
+
+zuul:value::
+~~~~~~~~~~~~
+
+Similar to zuul:attr, but used when documenting a literal value of an
+attribute.
+
+.. code-block:: rst
+
+   .. attr:: foo
+
+      Some text about foo.  It supports the following values:
+
+      .. value:: bar
+
+         One of the supported values for ``foo`` is ``bar``.
+
+      .. value:: baz
+
+         Another supported values for ``foo`` is ``baz``.
+
+.. attr:: foo
+   :noindex:
+
+   Some text about foo.  It supports the following values:
+
+   .. value:: bar
+      :noindex:
+
+      One of the supported values for ``foo`` is ``bar``.
+
+   .. value:: baz
+      :noindex:
+
+      Another supported values for ``foo`` is ``baz``.
+
+zuul:var::
+~~~~~~~~~~
+
+Also similar to zuul:attr, but used when documenting an Ansible
+variable which is available to a job's playbook.  In these cases, it's
+often necessary to indicate the variable may be an element of a list
+or dictionary, so this directive supports a ``type`` option.  It also
+supports the ``hidden`` option so that complex data structure
+definitions may continue across sections.  To use this, set the hidden
+option on a ``zuul:var::`` directive with the root of the data
+structure as the name.  Example:
+
+.. code-block:: rst
+
+   .. var:: foo
+
+      Foo is a dictionary with the following keys:
+
+      .. var:: items
+         :type: list
+
+         Items is a list of dictionaries with the following keys:
+
+         .. var:: bar
+
+            Text about bar
+
+   Section Boundary
+
+   .. var:: foo
+      :hidden:
+
+      .. var:: baz
+
+         Text about baz
+
+.. End of code block; start example
+
+.. var:: foo
+   :noindex:
+
+   Foo is a dictionary with the following keys:
+
+   .. var:: items
+      :noindex:
+      :type: list
+
+      Items is a list of dictionaries with the following keys:
+
+      .. var:: bar
+         :noindex:
+
+         Text about bar
+
+Section Boundary
+
+.. var:: foo
+   :noindex:
+   :hidden:
+
+   .. var:: baz
+      :noindex:
+
+      Text about baz
+
+.. End of example
+
+Zuul Sphinx Roles
+-----------------
+
+The following extra Sphinx roles are available.  Use these within the
+text when referring to attributes, values, and variables defined with
+the directives above.  Use these roles for the first appearance of an
+object within a subsection, but use the ````literal```` role in
+subsequent uses.
+
+:zuul:attr:
+~~~~~~~~~~~
+
+This creates a reference to the named attribute.  Provide the fully
+qualified name (e.g., ``:attr:`pipeline.manager```)
+
+:zuul:value:
+~~~~~~~~~~~~
+
+This creates a reference to the named value.  Provide the fully
+qualified name (e.g., ``:attr:`pipeline.manager.dependent```)
+
+:zuul:var:
+~~~~~~~~~~
+
+This creates a reference to the named variable.  Provide the fully
+qualified name (e.g., ``:var:`zuul.executor.name```)

doc/source/developer/index.rst

@@ -14,3 +14,4 @@ Zuul, though advanced users may find it interesting.
    drivers
    triggers
    testing
+   docs

zuul/sphinx/zuul.py

@@ -76,6 +76,7 @@ class ZuulAttrDirective(ZuulConfigObject):
     option_spec = {
         'required': lambda x: x,
         'default': lambda x: x,
+        'noindex': lambda x: x,
     }
 
     def before_content(self):
@@ -126,6 +127,7 @@ class ZuulVarDirective(ZuulConfigObject):
     option_spec = {
         'type': lambda x: x,
         'hidden': lambda x: x,
+        'noindex': lambda x: x,
     }
 
     type_map = {