From eec7affb53e406c72c20d10fc14d730ade1761b0 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Fri, 8 Oct 2021 20:50:37 +0200 Subject: manuals: start of documentation standards document This first version specifies how to create consistent SGV graphics (From yocto-docs rev: 370b9e34e9092c9eed22df2e8b2d0bb979487e5c) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/README | 13 +- documentation/standards.md | 103 ++++ documentation/template/template.svg | 1160 +++++++++++++++++++++++++++++++++++ 3 files changed, 1273 insertions(+), 3 deletions(-) create mode 100644 documentation/standards.md create mode 100644 documentation/template/template.svg (limited to 'documentation') diff --git a/documentation/README b/documentation/README index 2d9eb887b2..fccece0c9e 100644 --- a/documentation/README +++ b/documentation/README @@ -56,9 +56,16 @@ poky.yaml This file defines variables used for documentation production. The variables are used to define release pathnames, URLs for the published manuals, etc. -template -======== -Contains various templates, fonts, and some old PNG files. +standards.md +============ + +This file specifies some rules to follow when contributing to the documentation. + +template/ +========= + +Contains a template.svg, to make it easier to create consistent +SVG diagrams. Sphinx ====== diff --git a/documentation/standards.md b/documentation/standards.md new file mode 100644 index 0000000000..a2274f6d6e --- /dev/null +++ b/documentation/standards.md @@ -0,0 +1,103 @@ +# Standards for contributing to Yocto Project documentation + +This document attemps to standardize the way the Yocto Project +documentation is created. + +It is currently a work in progress. + +## Text standards + +This section has not been filled yet + +## ReStructured Text Syntax standards + +This section has not been filled yet + +## Adding screenshots + +The preferred format for adding screenshots is +[Portable Network Graphics (PNG)](https://en.wikipedia.org/wiki/Portable_Network_Graphics). +Compared to the JPEG format, PNG is lossless and compresses screenshots better. + +Screenshots are stored in a `figures/` subdirectory. + +To include a screenshot in PNG format: + + .. image:: figures/user-configuration.png + :align: center + +Depending on the size of the image, you may also shrink it +to prevent it from filling the whole page width: + + :scale: 50% + +For some types of screenshots, for example showing +programs displaying photographs or playing video, the JPEG +format may be more appropriate, because it is better at +compressing real-life images: + + .. image:: figures/vlc.jpg + :align: center + :scale: 75% + +## Adding new diagrams + +New diagrams should be added in +[Scalable Vector Graphics (SVG) format](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics). +Thanks to this, diagrams render nicely at any zoom level on generated documentation, +instead of being pixelated. + +The recommended tool for creating SVG diagrams for the Yocto Project +documentation is [Inkscape](https://inkscape.org/). + +### Colors + +The "GNOME HIG Colors" palette is used in our diagrams +(get it from +if you don't get it from Inkscape). + +It's easier to use than the default one in Inkscape, +as it has fewer but sufficient colors. This is a way +to guarantee that we use consistent colors across the +diagrams used in our documentation. + +See +for details about working with color palettes in Inkscape. + +### Template diagram + +The `template/` directory contains a `template.svg` file +to make it easier to create diagrams. +In particular, you can use it to copy standard text, shapes, +arrows and clipart to the new SVG document. + +### Fonts + +The recommended font for description text and labels is `Nimbus Roman`, size 10. +Labels are in bold. + +`template.svg` contains ready-to-copy labels. + +### Text boxes + +Text boxes are rectangle boxes, with rounded corners, and contain centered text +or labels. Their stroke color is slightly darker than their fill color. + +See `template.svg` for example boxes with different colors, which are ready +to be reused. + +### Clipart + +Only [Public Domain](https://en.wikipedia.org/wiki/Public_domain) +files are accepted for clipart. [Openclipart](https://openclipart.org) +is the best known and recommended source of such clipart. + +It is also required to state the source of each new clipart in the commit log, +to make it possible to check its origin. + +For the sake of consistency across diagrams, we recommend +to use existing cliparts, whenever possible. + +If cliparts in `template.svg` do not satisfy your requirements, you can +add to said file new cliparts, from e.g. Openclipart. Newly added +cliparts shall stay consistent in style and color with existing ones. diff --git a/documentation/template/template.svg b/documentation/template/template.svg new file mode 100644 index 0000000000..43043e3afb --- /dev/null +++ b/documentation/template/template.svg @@ -0,0 +1,1160 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Server / computer + Note: Public domain graphics from https://openclipart.org/ + + + + + Light 3box + + + + + + + + + + + + + + + + + + + + Blue 1box + + + Orange 1box + + Objets + Shapes + Logos + Arrows + Text + + + + Normal text + Orange 1 arrow + Blue 1 arrow + + Light 3 arrow + Label text (bold) + + + + -- cgit v1.2.3-54-g00ecf