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