James E. Blair | 32df6d8 | 2017-08-03 14:20:04 -0700 | [diff] [blame] | 1 | Documentation |
| 2 | ============= |
| 3 | |
| 4 | This is a brief style guide for Zuul documentation. |
| 5 | |
| 6 | ReStructuredText Conventions |
| 7 | ---------------------------- |
| 8 | |
| 9 | Code Blocks |
| 10 | ~~~~~~~~~~~ |
| 11 | |
| 12 | When showing a YAML example, use the ``.. code-block:: yaml`` |
| 13 | directive so that the sample appears as a code block with the correct |
| 14 | syntax highlighting. |
| 15 | |
| 16 | Literal Values |
| 17 | ~~~~~~~~~~~~~~ |
| 18 | |
| 19 | Filenames and literal values (such as when we instruct a user to type |
| 20 | a specific string into a configuration file) should use the RST |
| 21 | ````literal```` syntax. |
| 22 | |
James E. Blair | 9794019 | 2017-08-03 14:47:47 -0700 | [diff] [blame] | 23 | YAML supports boolean values expressed with or without an initial |
| 24 | capital letter. In examples and documentation, use ``true`` and |
| 25 | ``false`` in lowercase type because the resulting YAML is easier for |
| 26 | users to type and read. |
| 27 | |
James E. Blair | 32df6d8 | 2017-08-03 14:20:04 -0700 | [diff] [blame] | 28 | Terminology |
| 29 | ~~~~~~~~~~~ |
| 30 | |
| 31 | Zuul employs some specialized terminology. To help users become |
| 32 | acquainted with it, we employ a glossary. Observe the following: |
| 33 | |
| 34 | * Specialized terms should have entries in the glossary. |
| 35 | |
| 36 | * If the term is being defined in the text, don't link to the glossary |
| 37 | (that would be redundant), but do emphasize it with ``*italics*`` |
| 38 | the first time it appears in that definition. Subsequent uses |
| 39 | within the same subsection should be in regular type. |
| 40 | |
| 41 | * If it's being used (but not defined) in the text, link the first |
| 42 | usage within a subsection to the glossary using the ``:term:`` role, |
| 43 | but subsequent uses should be in regular type. |
| 44 | |
| 45 | * Be cognizant of how readers may jump to link targets within the |
| 46 | text, so be liberal in considering that once you cross a link |
| 47 | target, you may be in a new "subsection" for the above guideline. |
| 48 | |
| 49 | |
| 50 | Zuul Sphinx Directives |
| 51 | ---------------------- |
| 52 | |
| 53 | The following extra Sphinx directives are available in the ``zuul`` |
| 54 | domain. The ``zuul`` domain is configured as the default domain, so the |
| 55 | ``zuul:`` prefix may be omitted. |
| 56 | |
| 57 | zuul:attr:: |
| 58 | ~~~~~~~~~~~ |
| 59 | |
| 60 | This should be used when documenting Zuul configuration attributes. |
| 61 | Zuul configuration is heavily hierarchical, and this directive |
| 62 | facilitates documenting these by emphasising the hierarchy as |
| 63 | appropriate. It will annotate each configuration attribute with a |
| 64 | nice header with its own unique hyperlink target. It displays the |
| 65 | entire hierarchy of the attribute, but emphasises the last portion |
| 66 | (i.e., the field being documented). |
| 67 | |
David Shrewsbury | 1c61c71 | 2017-08-16 16:02:33 -0400 | [diff] [blame^] | 68 | To use the hierarchical features, simply nest with indentation in the |
James E. Blair | 32df6d8 | 2017-08-03 14:20:04 -0700 | [diff] [blame] | 69 | normal RST manner. |
| 70 | |
| 71 | It supports the ``required`` and ``default`` options and will annotate |
| 72 | the header appropriately. Example: |
| 73 | |
| 74 | .. code-block:: rst |
| 75 | |
| 76 | .. attr:: foo |
| 77 | |
| 78 | Some text about ``foo``. |
| 79 | |
| 80 | .. attr:: bar |
| 81 | :required: |
| 82 | :default: 42 |
| 83 | |
| 84 | Text about ``foo.bar``. |
| 85 | |
| 86 | .. attr:: foo |
| 87 | :noindex: |
| 88 | |
| 89 | Some text about ``foo``. |
| 90 | |
| 91 | .. attr:: bar |
| 92 | :noindex: |
| 93 | :required: |
| 94 | :default: 42 |
| 95 | |
| 96 | Text about ``foo.bar``. |
| 97 | |
| 98 | zuul:value:: |
| 99 | ~~~~~~~~~~~~ |
| 100 | |
| 101 | Similar to zuul:attr, but used when documenting a literal value of an |
| 102 | attribute. |
| 103 | |
| 104 | .. code-block:: rst |
| 105 | |
| 106 | .. attr:: foo |
| 107 | |
| 108 | Some text about foo. It supports the following values: |
| 109 | |
| 110 | .. value:: bar |
| 111 | |
| 112 | One of the supported values for ``foo`` is ``bar``. |
| 113 | |
| 114 | .. value:: baz |
| 115 | |
| 116 | Another supported values for ``foo`` is ``baz``. |
| 117 | |
| 118 | .. attr:: foo |
| 119 | :noindex: |
| 120 | |
| 121 | Some text about foo. It supports the following values: |
| 122 | |
| 123 | .. value:: bar |
| 124 | :noindex: |
| 125 | |
| 126 | One of the supported values for ``foo`` is ``bar``. |
| 127 | |
| 128 | .. value:: baz |
| 129 | :noindex: |
| 130 | |
| 131 | Another supported values for ``foo`` is ``baz``. |
| 132 | |
| 133 | zuul:var:: |
| 134 | ~~~~~~~~~~ |
| 135 | |
| 136 | Also similar to zuul:attr, but used when documenting an Ansible |
| 137 | variable which is available to a job's playbook. In these cases, it's |
| 138 | often necessary to indicate the variable may be an element of a list |
| 139 | or dictionary, so this directive supports a ``type`` option. It also |
| 140 | supports the ``hidden`` option so that complex data structure |
| 141 | definitions may continue across sections. To use this, set the hidden |
| 142 | option on a ``zuul:var::`` directive with the root of the data |
| 143 | structure as the name. Example: |
| 144 | |
| 145 | .. code-block:: rst |
| 146 | |
| 147 | .. var:: foo |
| 148 | |
| 149 | Foo is a dictionary with the following keys: |
| 150 | |
| 151 | .. var:: items |
| 152 | :type: list |
| 153 | |
| 154 | Items is a list of dictionaries with the following keys: |
| 155 | |
| 156 | .. var:: bar |
| 157 | |
| 158 | Text about bar |
| 159 | |
| 160 | Section Boundary |
| 161 | |
| 162 | .. var:: foo |
| 163 | :hidden: |
| 164 | |
| 165 | .. var:: baz |
| 166 | |
| 167 | Text about baz |
| 168 | |
| 169 | .. End of code block; start example |
| 170 | |
| 171 | .. var:: foo |
| 172 | :noindex: |
| 173 | |
| 174 | Foo is a dictionary with the following keys: |
| 175 | |
| 176 | .. var:: items |
| 177 | :noindex: |
| 178 | :type: list |
| 179 | |
| 180 | Items is a list of dictionaries with the following keys: |
| 181 | |
| 182 | .. var:: bar |
| 183 | :noindex: |
| 184 | |
| 185 | Text about bar |
| 186 | |
| 187 | Section Boundary |
| 188 | |
| 189 | .. var:: foo |
| 190 | :noindex: |
| 191 | :hidden: |
| 192 | |
| 193 | .. var:: baz |
| 194 | :noindex: |
| 195 | |
| 196 | Text about baz |
| 197 | |
| 198 | .. End of example |
| 199 | |
| 200 | Zuul Sphinx Roles |
| 201 | ----------------- |
| 202 | |
| 203 | The following extra Sphinx roles are available. Use these within the |
| 204 | text when referring to attributes, values, and variables defined with |
| 205 | the directives above. Use these roles for the first appearance of an |
| 206 | object within a subsection, but use the ````literal```` role in |
| 207 | subsequent uses. |
| 208 | |
| 209 | :zuul:attr: |
| 210 | ~~~~~~~~~~~ |
| 211 | |
| 212 | This creates a reference to the named attribute. Provide the fully |
| 213 | qualified name (e.g., ``:attr:`pipeline.manager```) |
| 214 | |
| 215 | :zuul:value: |
| 216 | ~~~~~~~~~~~~ |
| 217 | |
| 218 | This creates a reference to the named value. Provide the fully |
| 219 | qualified name (e.g., ``:attr:`pipeline.manager.dependent```) |
| 220 | |
| 221 | :zuul:var: |
| 222 | ~~~~~~~~~~ |
| 223 | |
| 224 | This creates a reference to the named variable. Provide the fully |
| 225 | qualified name (e.g., ``:var:`zuul.executor.name```) |