mirror of
https://git.yoctoproject.org/poky
synced 2026-04-23 09:32:17 +02:00
14c7cd24a5
Better for EPUB output in particular - Make some diagrams wider when necessary - Remove ":align: center" when we have ":width: 100%" - Update the standards.md files to mention this (From yocto-docs rev: 848ba7bd8984cc3f4bf6b818259865011cde0476) Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
132 lines
3.9 KiB
Markdown
132 lines
3.9 KiB
Markdown
# 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
|
|
|
|
### Project names
|
|
|
|
Project names should be capitalized in the same
|
|
way they are on Wikipedia, in particular:
|
|
|
|
* BitBake
|
|
* OpenEmbedded
|
|
|
|
There are exceptions in which such names can be used
|
|
in lower case:
|
|
|
|
* When referring to a package name
|
|
* When referring to the corresponding command name
|
|
* When used in a cross-reference title. Such
|
|
titles are usually in lower case.
|
|
|
|
### File names
|
|
|
|
File names should be quoted as in the below example:
|
|
|
|
``conf/local.conf``
|
|
|
|
Using "conf/local/conf" would be wrong.
|
|
|
|
## 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
|
|
|
|
A diagram with many details usually needs to use
|
|
the whole page width to be readable on all media.
|
|
In this case, the `:align:` directive is unnecessary:
|
|
|
|
:scale: 100%
|
|
|
|
Conversely, you may also shrink some images to
|
|
to prevent them 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 <https://gitlab.gnome.org/Teams/Design/HIG-app-icons/-/blob/master/GNOME%20HIG.gpl>
|
|
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 <https://inkscape-manuals.readthedocs.io/en/latest/palette.html>
|
|
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.
|