1.. _docs-style-rest: 2 3============================ 4reStructuredText style guide 5============================ 6.. inclusive-language: disable 7.. _reStructuredText: https://docutils.sourceforge.io/rst.html 8.. _Sphinx: https://www.sphinx-doc.org/en/master/ 9.. inclusive-language: enable 10 11This style guide defines Pigweed's conventions for `reStructuredText`_ (reST). 12``pigweed.dev`` documentation is authored in reST, not Markdown. Pigweed 13uses `Sphinx`_ to convert reST into HTML. 14 15.. tip:: ``pw format`` detects reST style issues. 16 17.. _docs-style-rest-overview: 18 19-------- 20Overview 21-------- 22 23.. _docs-style-rest-scope: 24 25Scope 26===== 27This style guide applies to all reST markup that's intended to be published to 28``pigweed.dev``. reST markup is mainly found in ``.rst`` files but it's also 29possible to embed reST within other types of files. 30 31.. _docs-style-rest-other: 32 33Related style guides 34==================== 35This style guide is narrowly focused on Pigweed's usage of reStructuredText. 36See :ref:`docs-contrib-docs` for other aspects of Pigweed documentation style. 37 38.. _docs-style-rest-headings: 39 40-------- 41Headings 42-------- 43Use the following syntax for headings. 44 45.. code-block:: rst 46 47 ================== 48 H1: Document title 49 ================== 50 In HTML the heading above is rendered as an H1 node. A page must have 51 exactly one H1 node. The H1 text must have equals signs (``=``) above 52 and below it. 53 54 ------------ 55 H2: Sections 56 ------------ 57 In HTML the heading above is rendered as an H2 node. The H2 text must have 58 minus signs (``-``) above and below it. H2 headings are conceptually similar 59 to chapters in a book. 60 61 H3: Subsections 62 =============== 63 In HTML the heading above is rendered as an H3 node. The H3 text must 64 have equals signs (``=``) below it. H3 headings are conceptually similar to 65 sections within a chapter of a book. 66 67 H4: Subsubsections 68 ------------------ 69 In HTML the heading above is rendered as an H4 node. The H4 text must have 70 minus signs (``-``) below it. H4 headings are used rarely. 71 72 H5: Subsubsubsections 73 ^^^^^^^^^^^^^^^^^^^^^ 74 In HTML the heading above is rendered as an H5 node. The H5 text must have 75 caret symbols (``^``) below it. H5 headings are used very rarely. 76 77 H6: Subsubsubsubsections 78 ........................ 79 In HTML the heading above is rendered as an H6 node. The H6 text must have 80 period symbols (``.``) below it. H6 headings are practically never used and 81 are an indicator that a document probably needs refactoring. 82 83.. _docs-style-rest-headings-order: 84 85Heading levels 86============== 87Headings must be used in hierarchical order. No level can be skipped. For 88example, you can't use an H1 heading followed by an H3. See 89`Headings and titles <https://developers.google.com/style/accessibility#headings-and-titles>`_. 90 91.. _docs-style-rest-headings-whitespace-after: 92 93No blank lines after headings 94============================= 95Don't put whitespace between a heading and the content that follows it. 96 97.. admonition:: **Yes** 98 :class: checkmark 99 100 .. code-block:: rst 101 102 Example heading 103 =============== 104 This paragraph is positioned correctly. 105 106.. admonition:: **No** 107 :class: error 108 109 .. code-block:: rst 110 111 Example heading 112 =============== 113 114 This paragraph isn't positioned correctly. There shouldn't be a blank 115 line above it. 116 117.. _docs-style-rest-headings-whitespace-before: 118 119One blank line before a heading 120=============================== 121Put one blank line between a heading and the content that comes before it. 122 123.. admonition:: **Yes** 124 :class: checkmark 125 126 .. code-block:: rst 127 128 This paragraph is positioned correctly. 129 130 Example heading 131 --------------- 132 ... 133 134.. admonition:: **No** 135 :class: error 136 137 .. code-block:: rst 138 139 This paragraph isn't positioned correctly. There's too much whitespace 140 below it. 141 142 143 144 Example heading 145 --------------- 146 ... 147 148.. _docs-style-rest-directives: 149 150---------- 151Directives 152---------- 153Indent directive content and attributes 3 spaces so that they align 154with the directive name. 155 156.. admonition:: **Yes** 157 :class: checkmark 158 159 .. code-block:: rst 160 161 .. my-directive:: 162 :my-attr: This attribute is positioned correctly. 163 164 This paragraph is positioned correctly. 165 166 .. my-nested-directive:: 167 168 This paragraph is positioned correctly. 169 170.. admonition:: **No** 171 :class: error 172 173 .. code-block:: rst 174 175 .. my-directive:: 176 177 This paragraph isn't positioned correctly. It has too few spaces. 178 179 .. my-directive:: 180 181 This paragraph isn't positioned correctly. It has too many spaces. 182 183Put a blank line between the directive and its content. Don't put space 184between a directive name and its attributes. 185 186.. admonition:: **Yes** 187 :class: checkmark 188 189 .. code-block:: rst 190 191 .. my-directive:: 192 :my-attr: This attribute is positioned correctly. 193 194 This paragraph is positioned correctly. 195 196.. admonition:: **No** 197 :class: error 198 199 .. code-block:: rst 200 201 .. my-directive:: 202 This paragraph isn't positioned correctly. There should be a blank 203 line above it. 204 205.. _docs-style-rest-tables: 206 207------ 208Tables 209------ 210.. _csv-table: https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table-1 211.. _list-table: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table 212.. _table: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table 213 214Prefer `list-table`_ and `csv-table`_. Avoid `table`_. ``list-table`` and 215``csv-table`` are easier to maintain. 216 217.. _docs-style-rest-includes: 218 219------------- 220Code includes 221------------- 222Prefer including code snippets from actual source code files that are built 223and tested regularly. 224 225To include a portion of a file: 226 227.. code-block:: rst 228 229 .. literalinclude:: my_source_file.py 230 :start-after: my-start-text 231 :end-before: my-end-text 232 233``my-start-text`` and ``my-end-text`` are the exclusive delimiters that must 234appear verbatim in the source file. 235 236.. _docs-style-rest-includes-python: 237 238Python code includes 239==================== 240.. inclusive-language: disable 241.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directives 242.. inclusive-language: enable 243 244Use `autodoc`_. 245 246Python code includes for CLI args 247--------------------------------- 248Use `argparse <https://sphinx-argparse.readthedocs.io/en/latest/usage.html>`_. 249 250.. _docs-style-rest-code-blocks: 251 252----------- 253Code blocks 254----------- 255.. _Languages: https://pygments.org/languages/ 256.. inclusive-language: disable 257.. _code-block: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block 258.. inclusive-language: enable 259 260Use `code-block`_. See `Languages`_ for the list of valid language 261keywords. 262 263If Google has a style guide for the programming language in your code block, 264your code should match Google's style guide. 265 266.. code-block:: rst 267 268 .. code-block:: c++ 269 270 // ... 271 272.. _docs-style-rest-toc: 273 274------------------------------------- 275Table of contents depth customization 276------------------------------------- 277Put ``:tocdepth: X`` on the first line of the page, where ``X`` equals how many 278levels of section heading you want to show in the page's table of contents. See 279``//docs/changelog.rst`` for an example. 280 281.. _docs-style-rest-cta: 282 283---------------------- 284Call-to-action buttons 285---------------------- 286Use ``grid`` and ``grid-item-card``. 287 288.. code-block:: 289 290 .. grid:: 2 291 292 .. grid-item-card:: :octicon:`<ICON>` <TITLE> 293 :link: <REF> 294 :link-type: <TYPE> 295 :class-item: <CLASS> 296 297 <DESCRIPTION> 298 299.. _Octicons: https://primer.style/foundations/icons 300.. inclusive-language: disable 301.. _ref: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role 302.. inclusive-language: enable 303 304* See `Octicons`_ for the list of valid ``<ICON>`` values. 305* ``<REF>`` can either be a `ref`_ or a full URL. 306* ``<TYPE>`` must be either ``ref`` or ``url``. 307* ``<CLASS>`` must be either ``sales-pitch-cta-primary`` or 308 ``sales-pitch-cta-secondary``. The top-left or top card should use 309 ``sales-pitch-cta-primary``; all the others should use 310 ``sales-pitch-cta-secondary``. The motivation is to draw extra attention to 311 the primary card. 312* ``<DESCRIPTION>`` should be reStructuredText describing what kind of 313 content you'll see if you click the card. 314 315.. _docs-style-rest-tabs: 316 317---- 318Tabs 319---- 320.. _Tabs: https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html 321 322Use ``tab-set`` and ``tab-item``. See `Tabs`_. 323 324.. code-block:: rst 325 326 .. tab-set:: 327 328 .. tab-item:: Linux 329 330 Linux instructions... 331 332 .. tab-item:: Windows 333 334 Windows instructions... 335 336Rendered output: 337 338.. tab-set:: 339 340 .. tab-item:: Linux 341 342 Linux instructions... 343 344 .. tab-item:: Windows 345 346 Windows instructions... 347 348.. _docs-style-rest-tabs-code: 349 350Tabs for code-only content 351========================== 352Use ``tab-set-code``. See `Languages`_ for the list of 353valid language keywords. 354 355.. code-block:: rst 356 357 .. tab-set-code:: 358 359 .. code-block:: c++ 360 361 // C++ code... 362 363 .. code-block:: python 364 365 # Python code... 366 367Rendered output: 368 369.. tab-set-code:: 370 371 .. code-block:: c++ 372 373 // C++ code... 374 375 .. code-block:: python 376 377 # Python code... 378 379.. _docs-style-rest-tabs-sync: 380 381Tab synchronization 382=================== 383Use the ``:sync:`` attribute to synchronize tabs for non-code content. See 384**Rendered output** below for an example. 385 386``tab-set-code`` tabs automatically synchronize by code language. 387 388.. code-block:: rst 389 390 .. tab-set:: 391 392 .. tab-item:: Linux 393 :sync: linux 394 395 Linux instructions... 396 397 .. tab-item:: Windows 398 :sync: windows 399 400 Windows instructions... 401 402 .. tab-set:: 403 404 .. tab-item:: Linux 405 :sync: linux 406 407 More Linux instructions... 408 409 .. tab-item:: Windows 410 :sync: windows 411 412 More Windows instructions... 413 414Rendered output: 415 416.. tab-set:: 417 418 .. tab-item:: Linux 419 :sync: linux 420 421 Linux instructions... 422 423 .. tab-item:: Windows 424 :sync: windows 425 426 Windows instructions... 427 428.. tab-set:: 429 430 .. tab-item:: Linux 431 :sync: linux 432 433 More Linux instructions... 434 435 .. tab-item:: Windows 436 :sync: windows 437 438 More Windows instructions... 439