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 10This section has not been filled yet 11 12## ReStructured Text Syntax standards 13 14This section has not been filled yet 15 16## Adding screenshots 17 18The preferred format for adding screenshots is 19[Portable Network Graphics (PNG)](https://en.wikipedia.org/wiki/Portable_Network_Graphics). 20Compared to the JPEG format, PNG is lossless and compresses screenshots better. 21 22Screenshots are stored in a `figures/` subdirectory. 23 24To include a screenshot in PNG format: 25 26 .. image:: figures/user-configuration.png 27 :align: center 28 29Depending on the size of the image, you may also shrink it 30to prevent it from filling the whole page width: 31 32 :scale: 50% 33 34For some types of screenshots, for example showing 35programs displaying photographs or playing video, the JPEG 36format may be more appropriate, because it is better at 37compressing real-life images: 38 39 .. image:: figures/vlc.jpg 40 :align: center 41 :scale: 75% 42 43## Adding new diagrams 44 45New diagrams should be added in 46[Scalable Vector Graphics (SVG) format](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics). 47Thanks to this, diagrams render nicely at any zoom level on generated documentation, 48instead of being pixelated. 49 50The recommended tool for creating SVG diagrams for the Yocto Project 51documentation is [Inkscape](https://inkscape.org/). 52 53### Colors 54 55The "GNOME HIG Colors" palette is used in our diagrams 56(get it from <https://gitlab.gnome.org/Teams/Design/HIG-app-icons/-/blob/master/GNOME%20HIG.gpl> 57if you don't get it from Inkscape). 58 59It's easier to use than the default one in Inkscape, 60as it has fewer but sufficient colors. This is a way 61to guarantee that we use consistent colors across the 62diagrams used in our documentation. 63 64See <https://inkscape-manuals.readthedocs.io/en/latest/palette.html> 65for details about working with color palettes in Inkscape. 66 67### Template diagram 68 69The `template/` directory contains a `template.svg` file 70to make it easier to create diagrams. 71In particular, you can use it to copy standard text, shapes, 72arrows and clipart to the new SVG document. 73 74### Fonts 75 76The recommended font for description text and labels is `Nimbus Roman`, size 10. 77Labels are in bold. 78 79`template.svg` contains ready-to-copy labels. 80 81### Text boxes 82 83Text boxes are rectangle boxes, with rounded corners, and contain centered text 84or labels. Their stroke color is slightly darker than their fill color. 85 86See `template.svg` for example boxes with different colors, which are ready 87to be reused. 88 89### Clipart 90 91Only [Public Domain](https://en.wikipedia.org/wiki/Public_domain) 92files are accepted for clipart. [Openclipart](https://openclipart.org) 93is the best known and recommended source of such clipart. 94 95It is also required to state the source of each new clipart in the commit log, 96to make it possible to check its origin. 97 98For the sake of consistency across diagrams, we recommend 99to use existing cliparts, whenever possible. 100 101If cliparts in `template.svg` do not satisfy your requirements, you can 102add to said file new cliparts, from e.g. Openclipart. Newly added 103cliparts shall stay consistent in style and color with existing ones. 104