1# Standards for contributing to Yocto Project documentation 2 3This document attemps to standardize the way the Yocto Project 4documentation is created. 5 6It is currently a work in progress. 7 8## Text standards 9 10### Bulleted lists 11 12Though Sphinx supports both the ``*`` and ``-`` characters 13for introducing bulleted lists, we have chosen to use 14only ``-`` for this purpose. 15 16Though not strictly required by Sphinx, we have also chosen 17to use two space characters after ``-`` to introduce each 18list item: 19 20 - Paragraph 1 21 22 - Paragraph 2 23 24As shown in the above example, there should also be an empty 25line between each list item. 26 27An exception to this rule is when the list items are just made 28of a few words, instead of entire paragraphs: 29 30 - Item 1 31 - Item 2 32 33This is again a matter of style, not syntax. 34 35### Line wrapping 36 37Source code for the documentation shouldn't have lines 38wider than 80 characters. This makes patch lines more 39readable and code easier to quote in e-mail clients. 40 41If you have to include long commands or lines in configuration 42files, provided the syntax makes this possible, split them 43into multiple lines, using the ``\`` character. 44 45Here is an example: 46 47 $ scripts/install-buildtools \ 48 --without-extended-buildtools \ 49 --base-url https://downloads.yoctoproject.org/releases/yocto \ 50 --release yocto-4.0.1 \ 51 --installer-version 4.0.1 52 53Exceptions are granted for file contents whose lines 54cannot be split without infringing syntactic rules 55or reducing readability, as well as for command output 56which should be kept unmodified. 57 58### Project names 59 60Project names should be capitalized in the same 61way they are on Wikipedia, in particular: 62 63* BitBake 64* OpenEmbedded 65 66There are exceptions in which such names can be used 67in lower case: 68 69* When referring to a package name 70* When referring to the corresponding command name 71* When used in a cross-reference title. Such 72 titles are usually in lower case. 73 74### File, tool and command names 75 76File, tool and command names should be double tick-quoted. 77For example, ``` ``conf/local.conf`` ``` is preferred over 78`"conf/local.conf"`. 79 80### Variables 81 82Every variable should be mentioned with: 83 84 :term:`VARIABLE` 85 86This assumes that `VARIABLE` is described either 87in the Yocto Project documentation variable index (`ref-manual/variables.rst`) 88or in the BitBake User Manual 89(`doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst`) 90 91If it is not described yet, the variable should be added to the 92glossary before or in the same patch it is used, so that `:term:` can be used. 93 94## ReStructured Text Syntax standards 95 96This section has not been filled yet 97 98## Adding screenshots 99 100The preferred format for adding screenshots is 101[Portable Network Graphics (PNG)](https://en.wikipedia.org/wiki/Portable_Network_Graphics). 102Compared to the JPEG format, PNG is lossless and compresses screenshots better. 103 104Screenshots are stored in a `figures/` subdirectory. 105 106To include a screenshot in PNG format: 107 108 .. image:: figures/user-configuration.png 109 :align: center 110 111A diagram with many details usually needs to use 112the whole page width to be readable on all media. 113In this case, the `:align:` directive is unnecessary: 114 115 :scale: 100% 116 117Conversely, you may also shrink some images to 118to prevent them from filling the whole page width: 119 120 :scale: 50% 121 122For some types of screenshots, for example showing 123programs displaying photographs or playing video, the JPEG 124format may be more appropriate, because it is better at 125compressing real-life images: 126 127 .. image:: figures/vlc.jpg 128 :align: center 129 :scale: 75% 130 131## Adding new diagrams 132 133New diagrams should be added in 134[Scalable Vector Graphics (SVG) format](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics). 135Thanks to this, diagrams render nicely at any zoom level on generated documentation, 136instead of being pixelated. 137 138The recommended tool for creating SVG diagrams for the Yocto Project 139documentation is [Inkscape](https://inkscape.org/). 140 141### Colors 142 143The "GNOME HIG Colors" palette is used in our diagrams 144(get it from <https://gitlab.gnome.org/Teams/Design/HIG-app-icons/-/blob/master/GNOME%20HIG.gpl> 145if you don't get it from Inkscape). 146 147It's easier to use than the default one in Inkscape, 148as it has fewer but sufficient colors. This is a way 149to guarantee that we use consistent colors across the 150diagrams used in our documentation. 151 152See <https://inkscape-manuals.readthedocs.io/en/latest/palette.html> 153for details about working with color palettes in Inkscape. 154 155### Template diagram 156 157The `template/` directory contains a `template.svg` file 158to make it easier to create diagrams. 159In particular, you can use it to copy standard text, shapes, 160arrows and clipart to the new SVG document. 161 162### Fonts 163 164The recommended font for description text and labels is `Nimbus Roman`, size 10. 165Labels are in bold. 166 167`template.svg` contains ready-to-copy labels. 168 169### Text boxes 170 171Text boxes are rectangle boxes, with rounded corners, and contain centered text 172or labels. Their stroke color is slightly darker than their fill color. 173 174See `template.svg` for example boxes with different colors, which are ready 175to be reused. 176 177### Clipart 178 179Only [Public Domain](https://en.wikipedia.org/wiki/Public_domain) 180files are accepted for clipart. [Openclipart](https://openclipart.org) 181is the best known and recommended source of such clipart. 182 183It is also required to state the source of each new clipart in the commit log, 184to make it possible to check its origin. 185 186For the sake of consistency across diagrams, we recommend 187to use existing cliparts, whenever possible. 188 189If cliparts in `template.svg` do not satisfy your requirements, you can 190add to said file new cliparts, from e.g. Openclipart. Newly added 191cliparts shall stay consistent in style and color with existing ones. 192