blob: be03bb119a04f676d81b5407d6f2f94d7e49eedc [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
35Folders exist for individual manuals as follows:
36
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 Geisslerd1e89492021-02-12 15:35:20 -060050go to https://www.yoctoproject.org and click on the "Documentation" 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
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 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
170The following headings styles are defined in Sphinx:
171
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
188 definitions. The definitions will then be referencable with the
189 [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
209to mimic the DocBook based documentation behavior. Variabes
210substitutions 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::
225 $ mkdir ~/poky-&DISTRO;
226 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",
240"warning", "admonition" that are supported, and additional directive
241can be added as Sphinx extension if needed.
242
243Figures
244=======
245
246The Yocto Project documentation has many figures/images. Sphinx has a
247'figure' directive which is straight forward to use. To include a
248figure 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
262References
263==========
264
265The following extension is enabed by default:
266sphinx.ext.autosectionlabel
267(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html).
268
269This extension allows you to refer sections by their titles. Note that
270autosectionlabel_prefix_document is enabled by default, so that we can
271insert references from any document.
272
273For example, to insert an HTML link to a section from
274documentaion/manual/intro.rst, use:
275
276 Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
277
278Alternatively a custom text can be used instead of using the section
279text:
280
281 Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>`
282
283TIP: The following command can be used to dump all the references that
284 are defined in the project documentation:
285
286 python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv
287
288This dump contains all links and for each link it shows the default
289"Link Text" that Sphinx would use. If the default link text is not
290appropriate, a custom link text can be used in the ':ref:' directive.
291
292Extlinks
293========
294
295The sphinx.ext.extlinks extension is enabled by default
296(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension),
297and it is configured with:
298
299 'yocto_home': ('https://yoctoproject.org%s', None),
300 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
301 'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
302 'yocto_lists': ('https://lists.yoctoproject.org%s', None),
303 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
304 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
305 'yocto_docs': ('https://docs.yoctoproject.org%s', None),
306 'yocto_git': ('https://git.yoctoproject.org%s', None),
307 'oe_home': ('https://www.openembedded.org%s', None),
308 'oe_lists': ('https://lists.openembedded.org%s', None),
309
310It creates convenient shortcuts which can be used throughout the
311documentation rst files, as:
312
313 Please check this :yocto_wiki:`wiki page </Weekly_Status>`
314
315Intersphinx links
316=================
317
318The sphinx.ext.intersphinx extension is enabled by default
319(https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),
320so that we can cross reference content from other Sphinx based
321documentation projects, such as the BitBake manual.
322
323References to the bitbake manual can be done like this:
324
325 See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
326or
327 :term:`bitbake:BB_NUMBER_PARSE_THREADS`
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600328
329Submitting documentation changes
330================================
331
332Please see the top level README file in this repository for details of where
333to send patches.