blob: fe86876ee7bfcedb65459d3357a8e02115a3253f [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001documentation
2=============
3
4This is the directory that contains the Yocto Project documentation. The Yocto
5Project source repositories at http://git.yoctoproject.org/cgit.cgi have two
6instances of the "documentation" directory. You should understand each of
7these instances.
8
9 poky/documentation - The directory within the poky Git repository containing
10 the set of Yocto Project manuals. When you clone the
11 poky Git repository, the documentation directory
12 contains the manuals. The state of the manuals in this
13 directory is guaranteed to reflect the latest Yocto
14 Project release. The manuals at the tip of this
15 directory will also likely contain most manual
16 development changes.
17
18 yocto-docs/documentation - The Git repository for the Yocto Project manuals.
19 This repository is where manual development
20 occurs. If you plan on contributing back to the
21 Yocto Project documentation, you should set up
22 a local Git repository based on this upstream
23 repository as follows:
24
25 git clone git://git.yoctoproject.org/yocto-docs
26
27 Changes and patches are first pushed to the
28 yocto-docs Git repository. Later, they make it
29 into the poky Git repository found at
30 git://git.yoctoproject.org/poky.
31
32Manual Organization
33===================
34
35Folders exist for individual manuals as follows:
36
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050037* sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050038* bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide
Brad Bishopd7bf8c12018-02-25 22:55:05 -050039* dev-manual - The Yocto Project Development Tasks Manual
40* kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual
Patrick Williamsc124f4f2015-09-15 14:41:29 -050041* ref-manual - The Yocto Project Reference Manual
42* yocto-project-qs - The Yocto Project Quick Start
Patrick Williamsc124f4f2015-09-15 14:41:29 -050043* profile-manual - The Yocto Project Profile and Tracing Manual
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050044* toaster-manual - The Toaster Manual
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050045* test-manual - The Test Environment Manual
Patrick Williamsc124f4f2015-09-15 14:41:29 -050046
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050047Each folder is self-contained regarding content and figures.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050048
49If you want to find HTML versions of the Yocto Project manuals on the web,
50go to http://www.yoctoproject.org and click on the "Documentation" tab. From
51there you have access to archived documentation from previous releases, current
52documentation for the latest release, and "Docs in Progress" for the release
53currently being developed.
54
55In general, the Yocto Project site (http://www.yoctoproject.org) is a great
56reference for both information and downloads.
57
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050058poky.yaml
59=========
Patrick Williamsc124f4f2015-09-15 14:41:29 -050060
61This file defines variables used for documentation production. The variables
62are used to define release pathnames, URLs for the published manuals, etc.
63
64template
65========
66Contains various templates, fonts, and some old PNG files.
67
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050068Sphinx
69======
70
71The Yocto Project documentation was migrated from the original DocBook
72format to Sphinx based documentation for the Yocto Project 3.2
73release. This section will provide additional information related to
74the Sphinx migration, and guidelines for developers willing to
75contribute to the Yocto Project documentation.
76
77 Sphinx is a tool that makes it easy to create intelligent and
78 beautiful documentation, written by Georg Brandl and licensed under
79 the BSD license. It was originally created for the Python
80 documentation.
81
82Extensive documentation is available on the Sphinx website:
83https://www.sphinx-doc.org/en/master/. Sphinx is designed to be
84extensible thanks to the ability to write our own custom extensions,
85as Python modules, which will be executed during the generation of the
86documentation.
87
88Yocto Project documentation website
89===================================
90
91A new website has been created to host the Yocto Project
92documentation, it can be found at: https://docs.yoctoproject.org/.
93
94The entire Yocto Project documentation, as well as the BitBake manual
95is published on this website, including all previously released
96versions. A version switcher was added, as a drop-down menu on the top
97of the page to switch back and forth between the various versions of
98the current active Yocto Project releases.
99
100Transition pages have been added (as rst file) to show links to old
101versions of the Yocto Project documentation with links to each manual
102generated with DocBook.
103
104How to build the Yocto Project documentation
105============================================
106
107Sphinx is written in Python. While it might work with Python2, for
108obvious reasons, we will only support building the Yocto Project
109documentation with Python3.
110
111Sphinx might be available in your Linux distro packages repositories,
112however it is not recommend using distro packages, as they might be
113old versions, especially if you are using an LTS version of your
114distro. The recommended method to install Sphinx and all required
115dependencies is to use the Python Package Index (pip).
116
117To install all required packages run:
118
119 $ pip3 install sphinx sphinx_rtd_theme pyyaml
120
121To build the documentation locally, run:
122
123 $ cd documentation
Andrew Geissleraf5e4ef2020-10-16 10:22:50 -0500124 $ make html
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500125
126The resulting HTML index page will be _build/html/index.html, and you
127can browse your own copy of the locally generated documentation with
128your browser.
129
130Sphinx theme and CSS customization
131==================================
132
133The Yocto Project documentation is currently based on the "Read the
134Docs" Sphinx theme, with a few changes to make sure the look and feel
135of the project documentation is preserved.
136
137Most of the theme changes can be done using the file
138'sphinx-static/theme_overrides.css'. Most CSS changes in this file
139were inherited from the DocBook CSS stylesheets.
140
141Sphinx design guidelines and principles
142=======================================
143
144The initial Docbook to Sphinx migration was done with an automated
145tool called Pandoc (https://pandoc.org/). The tool produced some clean
146output markdown text files. After the initial automated conversion
147additional changes were done to fix up headings, images and links. In
148addition Sphinx has built in mechanisms (directives) which were used
149to replace similar functions implemented in Docbook such as glossary,
150variables substitutions, notes and references.
151
152Headings
153========
154
155The layout of the Yocto Project manuals is organized as follows
156
157 Book
158 Chapter
159 Section
160 Section
161 Section
162
163The following headings styles are defined in Sphinx:
164
165 Book => overline ===
166 Chapter => overline ***
167 Section => ====
168 Section => ----
169 Section => ^^^^
170 Section => """" or ~~~~
171
172With this proposal, we preserve the same TOCs between Sphinx and Docbook.
173
174Built-in glossary
175=================
176
177Sphinx has a glossary directive. From
178https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary:
179
180 This directive must contain a reST definition list with terms and
181 definitions. The definitions will then be referencable with the
182 [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term
183 'term' role].
184
185So anywhere in any of the Yocto Project manuals, :term:`VAR` can be
186used to refer to an item from the glossary, and a link is created
187automatically. A general index of terms is also generated by Sphinx
188automatically.
189
190Global substitutions
191====================
192
193The Yocto Project documentation makes heavy use of global
194variables. In Docbook these variables are stored in the file
195poky.ent. This Docbook feature is not handled automatically with
196Pandoc. Sphinx has builtin support for substitutions
197(https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions),
198however there are important shortcomings. For example they cannot be
199used/nested inside code-block sections.
200
201A Sphinx extension was implemented to support variable substitutions
202to mimic the DocBook based documentation behavior. Variabes
203substitutions are done while reading/parsing the .rst files. The
204pattern for variables substitutions is the same as with DocBook,
205e.g. `&VAR;`.
206
207The implementation of the extension can be found here in the file
208documentation/sphinx/yocto-vars.py, this extension is enabled by
209default when building the Yocto Project documentation. All variables
210are set in a file call poky.yaml, which was initially generated from
211poky.ent. The file was converted into YAML so that it is easier to
212process by the custom Sphinx extension (which is a Python module).
213
214For example, the following .rst content will produce the 'expected'
215content:
216
217 .. code-block::
218 $ mkdir ~/poky-&DISTRO;
219 or
220 $ git clone &YOCTO_GIT_URL;/git/poky -b &DISTRO_NAME_NO_CAP;
221
222Variables can be nested, like it was the case for DocBook:
223
224 YOCTO_HOME_URL : "http://www.yoctoproject.org"
225 YOCTO_DOCS_URL : "&YOCTO_HOME_URL;/docs"
226
227Note directive
228==============
229
230Sphinx has a builtin 'note' directive that produces clean Note section
231in the output file. There are various types of directives such as
232"attention", "caution", "danger", "error", "hint", "important", "tip",
233"warning", "admonition" that are supported, and additional directive
234can be added as Sphinx extension if needed.
235
236Figures
237=======
238
239The Yocto Project documentation has many figures/images. Sphinx has a
240'figure' directive which is straight forward to use. To include a
241figure in the body of the documentation:
242
243 .. image:: figures/YP-flow-diagram.png
244
245Links and References
246====================
247
248The following types of links can be used: links to other locations in
249the same document, to locations in other documents and to external
250websites.
251
252More information can be found here:
253https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
254
255References
256==========
257
258The following extension is enabed by default:
259sphinx.ext.autosectionlabel
260(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html).
261
262This extension allows you to refer sections by their titles. Note that
263autosectionlabel_prefix_document is enabled by default, so that we can
264insert references from any document.
265
266For example, to insert an HTML link to a section from
267documentaion/manual/intro.rst, use:
268
269 Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
270
271Alternatively a custom text can be used instead of using the section
272text:
273
274 Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>`
275
276TIP: The following command can be used to dump all the references that
277 are defined in the project documentation:
278
279 python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv
280
281This dump contains all links and for each link it shows the default
282"Link Text" that Sphinx would use. If the default link text is not
283appropriate, a custom link text can be used in the ':ref:' directive.
284
285Extlinks
286========
287
288The sphinx.ext.extlinks extension is enabled by default
289(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension),
290and it is configured with:
291
292 'yocto_home': ('https://yoctoproject.org%s', None),
293 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
294 'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
295 'yocto_lists': ('https://lists.yoctoproject.org%s', None),
296 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
297 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
298 'yocto_docs': ('https://docs.yoctoproject.org%s', None),
299 'yocto_git': ('https://git.yoctoproject.org%s', None),
300 'oe_home': ('https://www.openembedded.org%s', None),
301 'oe_lists': ('https://lists.openembedded.org%s', None),
302
303It creates convenient shortcuts which can be used throughout the
304documentation rst files, as:
305
306 Please check this :yocto_wiki:`wiki page </Weekly_Status>`
307
308Intersphinx links
309=================
310
311The sphinx.ext.intersphinx extension is enabled by default
312(https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),
313so that we can cross reference content from other Sphinx based
314documentation projects, such as the BitBake manual.
315
316References to the bitbake manual can be done like this:
317
318 See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
319or
320 :term:`bitbake:BB_NUMBER_PARSE_THREADS`