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-code-blocks-shell: 273 274Code blocks for CLI interactions 275================================ 276Use ``.. code-block:: shell`` for Bash scripts and 277``.. code-block:: fish`` for Fish scripts. 278 279.. _docs-style-rest-code-blocks-console: 280 281Code blocks for CLI interactions 282================================ 283.. _console: https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer 284 285Use ``.. code-block:: console`` for UNIX CLI interactions and 286``.. code-block:: doscon`` for DOS CLI interactions. 287 288.. tab-set:: 289 290 .. tab-item:: Linux and macOS 291 292 Use ``.. code-block:: console``. 293 294 Use the ``$`` starting prompt if the command can be run with 295 normal user privileges. Use ``#`` if the command requires root 296 privileges. These prompts are required because they help Pygments 297 parse the code correctly. 298 299 Continue a command on another line with ``\\``. Start the 300 continuation lines with ``>``. 301 302 .. code-block:: text 303 304 .. code-block:: console 305 306 $ ls -a 307 . .. a b c 308 $ echo \ 309 > test 310 test 311 $ su 312 # ls -a 313 . .. a b c 314 315 .. tab-item:: Windows 316 317 Use ``.. code-block:: doscon``. 318 319 Use the ``>`` starting prompt. This prompt helps Pygments 320 parse the code correctly. 321 322 Continue a command on another line with ``^``. Start the 323 continuation lines with ``More?``. 324 325 .. code-block:: text 326 327 .. code-block:: doscon 328 329 > copy ^ 330 More? source.txt ^ 331 destination.txt 332 333.. _docs-style-rest-toc: 334 335------------------------------------- 336Table of contents depth customization 337------------------------------------- 338Put ``:tocdepth: X`` on the first line of the page, where ``X`` equals how many 339levels of section heading you want to show in the page's table of contents. See 340``//docs/changelog.rst`` for an example. 341 342.. _docs-style-rest-cta: 343 344---------------------- 345Call-to-action buttons 346---------------------- 347Use ``grid`` and ``grid-item-card``. 348 349.. code-block:: 350 351 .. grid:: 2 352 353 .. grid-item-card:: :octicon:`<ICON>` <TITLE> 354 :link: <REF> 355 :link-type: <TYPE> 356 :class-item: <CLASS> 357 358 <DESCRIPTION> 359 360.. _Octicons: https://primer.style/foundations/icons 361.. inclusive-language: disable 362.. _ref: https://www.sphinx-doc.org/en/master/usage/referencing.html#ref-role 363.. inclusive-language: enable 364 365* See `Octicons`_ for the list of valid ``<ICON>`` values. 366* ``<REF>`` can either be a `ref`_ or a full URL. 367* ``<TYPE>`` must be either ``ref`` or ``url``. 368* ``<CLASS>`` must be either ``sales-pitch-cta-primary`` or 369 ``sales-pitch-cta-secondary``. The top-left or top card should use 370 ``sales-pitch-cta-primary``; all the others should use 371 ``sales-pitch-cta-secondary``. The motivation is to draw extra attention to 372 the primary card. 373* ``<DESCRIPTION>`` should be reStructuredText describing what kind of 374 content you'll see if you click the card. 375 376.. _docs-style-rest-tabs: 377 378---- 379Tabs 380---- 381.. _Tabs: https://sphinx-design.readthedocs.io/en/furo-theme/tabs.html 382 383Use ``tab-set`` and ``tab-item``. See `Tabs`_. 384 385.. code-block:: rst 386 387 .. tab-set:: 388 389 .. tab-item:: Linux 390 391 Linux instructions... 392 393 .. tab-item:: Windows 394 395 Windows instructions... 396 397Rendered output: 398 399.. tab-set:: 400 401 .. tab-item:: Linux 402 403 Linux instructions... 404 405 .. tab-item:: Windows 406 407 Windows instructions... 408 409.. _docs-style-rest-tabs-code: 410 411Tabs for code-only content 412========================== 413Use ``tab-set-code``. See `Languages`_ for the list of 414valid language keywords. 415 416.. code-block:: rst 417 418 .. tab-set-code:: 419 420 .. code-block:: c++ 421 422 // C++ code... 423 424 .. code-block:: python 425 426 # Python code... 427 428Rendered output: 429 430.. tab-set-code:: 431 432 .. code-block:: c++ 433 434 // C++ code... 435 436 .. code-block:: python 437 438 # Python code... 439 440.. _docs-style-rest-tabs-sync: 441 442Tab synchronization 443=================== 444Use the ``:sync:`` attribute to synchronize tabs for non-code content. See 445**Rendered output** below for an example. 446 447``tab-set-code`` tabs automatically synchronize by code language. 448 449.. code-block:: rst 450 451 .. tab-set:: 452 453 .. tab-item:: Linux 454 :sync: linux 455 456 Linux instructions... 457 458 .. tab-item:: Windows 459 :sync: windows 460 461 Windows instructions... 462 463 .. tab-set:: 464 465 .. tab-item:: Linux 466 :sync: linux 467 468 More Linux instructions... 469 470 .. tab-item:: Windows 471 :sync: windows 472 473 More Windows instructions... 474 475Rendered output: 476 477.. tab-set:: 478 479 .. tab-item:: Linux 480 :sync: linux 481 482 Linux instructions... 483 484 .. tab-item:: Windows 485 :sync: windows 486 487 Windows instructions... 488 489.. tab-set:: 490 491 .. tab-item:: Linux 492 :sync: linux 493 494 More Linux instructions... 495 496 .. tab-item:: Windows 497 :sync: windows 498 499 More Windows instructions... 500