diff options
Diffstat (limited to 'poky/documentation/standards.md')
-rw-r--r-- | poky/documentation/standards.md | 68 |
1 files changed, 64 insertions, 4 deletions
diff --git a/poky/documentation/standards.md b/poky/documentation/standards.md index 81aff5f193..9f4771ebd9 100644 --- a/poky/documentation/standards.md +++ b/poky/documentation/standards.md @@ -7,6 +7,54 @@ It is currently a work in progress. ## Text standards +### Bulleted lists + +Though Sphinx supports both the ``*`` and ``-`` characters +for introducing bulleted lists, we have chosen to use +only ``-`` for this purpose. + +Though not strictly required by Sphinx, we have also chosen +to use two space characters after ``-`` to introduce each +list item: + + - Paragraph 1 + + - Paragraph 2 + +As shown in the above example, there should also be an empty +line between each list item. + +An exception to this rule is when the list items are just made +of a few words, instead of entire paragraphs: + + - Item 1 + - Item 2 + +This is again a matter of style, not syntax. + +### Line wrapping + +Source code for the documentation shouldn't have lines +wider than 80 characters. This makes patch lines more +readable and code easier to quote in e-mail clients. + +If you have to include long commands or lines in configuration +files, provided the syntax makes this possible, split them +into multiple lines, using the ``\`` character. + +Here is an example: + + $ scripts/install-buildtools \ + --without-extended-buildtools \ + --base-url https://downloads.yoctoproject.org/releases/yocto \ + --release yocto-4.0.1 \ + --installer-version 4.0.1 + +Exceptions are granted for file contents whose lines +cannot be split without infringing syntactic rules +or reducing readability, as well as for command output +which should be kept unmodified. + ### Project names Project names should be capitalized in the same @@ -23,13 +71,25 @@ in lower case: * When used in a cross-reference title. Such titles are usually in lower case. -### File names +### File, tool and command names + +File, tool and command names should be double tick-quoted. +For example, ``` ``conf/local.conf`` ``` is preferred over +`"conf/local.conf"`. + +### Variables + +Every variable should be mentioned with: -File names should be quoted as in the below example: + :term:`VARIABLE` - ``conf/local.conf`` +This assumes that `VARIABLE` is described either +in the Yocto Project documentation variable index (`ref-manual/variables.rst`) +or in the BitBake User Manual +(`doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst`) -Using "conf/local/conf" would be wrong. +If it is not described yet, the variable should be added to the +glossary before or in the same patch it is used, so that `:term:` can be used. ## ReStructured Text Syntax standards |