blob: fad19683c1d2f3e9242c4d26d9ae5f400bb34d8b [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
Andrew Geisslerd1e89492021-02-12 15:35:20 -06005Project source repositories at https://git.yoctoproject.org/cgit.cgi have two
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006instances 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
William A. Kennington IIIac69b482021-06-02 12:28:27 -070035Here the folders corresponding to individual manuals:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036
Andrew Geissler6ce62a22020-11-30 19:58:47 -060037* sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide.
38* bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide
39* dev-manual - The Yocto Project Development Tasks Manual
40* kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual
41* ref-manual - The Yocto Project Reference Manual
42* brief-yoctoprojectqs - The Yocto Project Quick Start
43* profile-manual - The Yocto Project Profile and Tracing Manual
44* toaster-manual - The Toaster Manual
45* 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,
Andrew Geissler95ac1b82021-03-31 14:34:31 -050050go to https://www.yoctoproject.org and click on the "Docs" tab. From
Patrick Williamsc124f4f2015-09-15 14:41:29 -050051there 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
Andrew Geisslerd1e89492021-02-12 15:35:20 -060055In general, the Yocto Project site (https://www.yoctoproject.org) is a great
Patrick Williamsc124f4f2015-09-15 14:41:29 -050056reference 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
Andrew Geissler09036742021-06-25 14:25:14 -050091The website hosting the Yocto Project documentation, can be found
92at: https://docs.yoctoproject.org/.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050093
Andrew Geissler95ac1b82021-03-31 14:34:31 -050094The entire Yocto Project documentation, as well as the BitBake manual,
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050095is 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
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500100Transition pages have been added (as rst files) to show links to old
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500101versions 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,
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500112however it is not recommended to use distro packages, as they might be
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500113old 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 Geisslerf0343792020-11-18 10:42:21 -0600124 $ 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
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600130Alternatively, you can use Pipenv to automatically install all required
131dependencies in a virtual environment:
132
133 $ cd documentation
134 $ pipenv install
135 $ pipenv run make html
136
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500137Sphinx theme and CSS customization
138==================================
139
140The Yocto Project documentation is currently based on the "Read the
141Docs" Sphinx theme, with a few changes to make sure the look and feel
142of the project documentation is preserved.
143
144Most of the theme changes can be done using the file
145'sphinx-static/theme_overrides.css'. Most CSS changes in this file
146were inherited from the DocBook CSS stylesheets.
147
148Sphinx design guidelines and principles
149=======================================
150
151The initial Docbook to Sphinx migration was done with an automated
152tool called Pandoc (https://pandoc.org/). The tool produced some clean
153output markdown text files. After the initial automated conversion
154additional changes were done to fix up headings, images and links. In
155addition Sphinx has built in mechanisms (directives) which were used
156to replace similar functions implemented in Docbook such as glossary,
157variables substitutions, notes and references.
158
159Headings
160========
161
162The layout of the Yocto Project manuals is organized as follows
163
164 Book
165 Chapter
166 Section
167 Section
168 Section
169
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700170Here are the heading styles defined in Sphinx:
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500171
172 Book => overline ===
173 Chapter => overline ***
174 Section => ====
175 Section => ----
176 Section => ^^^^
177 Section => """" or ~~~~
178
179With this proposal, we preserve the same TOCs between Sphinx and Docbook.
180
181Built-in glossary
182=================
183
184Sphinx has a glossary directive. From
185https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary:
186
187 This directive must contain a reST definition list with terms and
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500188 definitions. It's then possible to refer to each definition through the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500189 [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term
190 'term' role].
191
192So anywhere in any of the Yocto Project manuals, :term:`VAR` can be
193used to refer to an item from the glossary, and a link is created
194automatically. A general index of terms is also generated by Sphinx
195automatically.
196
197Global substitutions
198====================
199
200The Yocto Project documentation makes heavy use of global
201variables. In Docbook these variables are stored in the file
202poky.ent. This Docbook feature is not handled automatically with
203Pandoc. Sphinx has builtin support for substitutions
204(https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions),
205however there are important shortcomings. For example they cannot be
206used/nested inside code-block sections.
207
208A Sphinx extension was implemented to support variable substitutions
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500209to mimic the DocBook based documentation behavior. Variable
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500210substitutions are done while reading/parsing the .rst files. The
211pattern for variables substitutions is the same as with DocBook,
212e.g. `&VAR;`.
213
214The implementation of the extension can be found here in the file
215documentation/sphinx/yocto-vars.py, this extension is enabled by
216default when building the Yocto Project documentation. All variables
217are set in a file call poky.yaml, which was initially generated from
218poky.ent. The file was converted into YAML so that it is easier to
219process by the custom Sphinx extension (which is a Python module).
220
221For example, the following .rst content will produce the 'expected'
222content:
223
224 .. code-block::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500225 $ mkdir poky-&DISTRO;
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500226 or
227 $ git clone &YOCTO_GIT_URL;/git/poky -b &DISTRO_NAME_NO_CAP;
228
229Variables can be nested, like it was the case for DocBook:
230
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600231 YOCTO_HOME_URL : "https://www.yoctoproject.org"
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500232 YOCTO_DOCS_URL : "&YOCTO_HOME_URL;/docs"
233
234Note directive
235==============
236
237Sphinx has a builtin 'note' directive that produces clean Note section
238in the output file. There are various types of directives such as
239"attention", "caution", "danger", "error", "hint", "important", "tip",
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500240"warning", "admonition" that are supported, and additional directives
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500241can be added as Sphinx extension if needed.
242
243Figures
244=======
245
246The Yocto Project documentation has many figures/images. Sphinx has a
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500247'figure' directive which is straightforward to use. To include a
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500248figure in the body of the documentation:
249
250 .. image:: figures/YP-flow-diagram.png
251
252Links and References
253====================
254
255The following types of links can be used: links to other locations in
256the same document, to locations in other documents and to external
257websites.
258
259More information can be found here:
260https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
261
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500262Anchor (<#link>) links are forbidden as they are not checked by Sphinx during
263the build and may be broken without knowing about it.
264
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500265References
266==========
267
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500268The following extension is enabled by default:
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500269sphinx.ext.autosectionlabel
270(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html).
271
272This extension allows you to refer sections by their titles. Note that
273autosectionlabel_prefix_document is enabled by default, so that we can
274insert references from any document.
275
276For example, to insert an HTML link to a section from
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500277documentation/manual/intro.rst, use:
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500278
279 Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
280
281Alternatively a custom text can be used instead of using the section
282text:
283
284 Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>`
285
286TIP: The following command can be used to dump all the references that
287 are defined in the project documentation:
288
289 python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv
290
291This dump contains all links and for each link it shows the default
292"Link Text" that Sphinx would use. If the default link text is not
293appropriate, a custom link text can be used in the ':ref:' directive.
294
295Extlinks
296========
297
298The sphinx.ext.extlinks extension is enabled by default
299(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension),
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500300and it is configured with the 'extlinks' definitions in
301the 'documentation/conf.py' file:
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500302
303 'yocto_home': ('https://yoctoproject.org%s', None),
304 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
305 'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
306 'yocto_lists': ('https://lists.yoctoproject.org%s', None),
307 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
308 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
309 'yocto_docs': ('https://docs.yoctoproject.org%s', None),
310 'yocto_git': ('https://git.yoctoproject.org%s', None),
311 'oe_home': ('https://www.openembedded.org%s', None),
312 'oe_lists': ('https://lists.openembedded.org%s', None),
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500313 'oe_git': ('https://git.openembedded.org%s', None),
314 'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
315 'oe_layerindex': ('https://layers.openembedded.org%s', None),
316 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500317
318It creates convenient shortcuts which can be used throughout the
319documentation rst files, as:
320
321 Please check this :yocto_wiki:`wiki page </Weekly_Status>`
322
323Intersphinx links
324=================
325
326The sphinx.ext.intersphinx extension is enabled by default
327(https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),
328so that we can cross reference content from other Sphinx based
329documentation projects, such as the BitBake manual.
330
Patrick Williams213cb262021-08-07 19:21:33 -0500331References to the BitBake manual can be done:
332 - With a specific description instead of the section name:
333 :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
334 - With the section name:
335 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option
336 - Linking to the entire BitBake manual:
337 :doc:`BitBake User Manual <bitbake:index>`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500338
Patrick Williams213cb262021-08-07 19:21:33 -0500339Note that a reference to a variable (:term:`VARIABLE`) automatically points to
340the BitBake manual if the variable is not described in the Reference Manual's Variable Glossary.
341However, if you need to bypass this, you can explicitely refer to a description in the
342BitBake manual as follows:
343
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500344 :term:`bitbake:BB_NUMBER_PARSE_THREADS`
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600345
346Submitting documentation changes
347================================
348
349Please see the top level README file in this repository for details of where
350to send patches.