1documentation 2============= 3 4This is the directory that contains the Yocto Project documentation. The Yocto 5Project source repositories at https://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 35Here the folders corresponding to individual manuals: 36 37* brief-yoctoprojectqs - Yocto Project Quick Start 38* overview-manual - Yocto Project Overview and Concepts Manual 39* contributor-guide - Yocto Project and OpenEmbedded Contributor Guide 40* ref-manual - Yocto Project Reference Manual 41* bsp-guide - Yocto Project Board Support Package (BSP) Developer's Guide 42* dev-manual - Yocto Project Development Tasks Manual 43* kernel-dev - Yocto Project Linux Kernel Development Manual 44* profile-manual - Yocto Project Profiling and Tracing Manual 45* sdk-manual - Yocto Project Software Development Kit (SDK) Developer's Guide. 46* toaster-manual - Toaster User Manual 47* test-manual - Yocto Project Test Environment Manual 48* migration-guides - Yocto Project Release and Migration Notes 49 50Each folder is self-contained regarding content and figures. 51 52If you want to find HTML versions of the Yocto Project manuals on the web, 53the current versions reside at https://docs.yoctoproject.org. 54 55poky.yaml 56========= 57 58This file defines variables used for documentation production. The variables 59are used to define release pathnames, URLs for the published manuals, etc. 60 61standards.md 62============ 63 64This file specifies some rules to follow when contributing to the documentation. 65 66template/ 67========= 68 69Contains a template.svg, to make it easier to create consistent 70SVG diagrams. 71 72Sphinx 73====== 74 75The Yocto Project documentation was migrated from the original DocBook 76format to Sphinx based documentation for the Yocto Project 3.2 77release. This section will provide additional information related to 78the Sphinx migration, and guidelines for developers willing to 79contribute to the Yocto Project documentation. 80 81 Sphinx is a tool that makes it easy to create intelligent and 82 beautiful documentation, written by Georg Brandl and licensed under 83 the BSD license. It was originally created for the Python 84 documentation. 85 86Extensive documentation is available on the Sphinx website: 87https://www.sphinx-doc.org/en/master/. Sphinx is designed to be 88extensible thanks to the ability to write our own custom extensions, 89as Python modules, which will be executed during the generation of the 90documentation. 91 92Yocto Project documentation website 93=================================== 94 95The website hosting the Yocto Project documentation, can be found 96at: https://docs.yoctoproject.org/. 97 98The entire Yocto Project documentation, as well as the BitBake manual, 99is published on this website, including all previously released 100versions. A version switcher was added, as a drop-down menu on the top 101of the page to switch back and forth between the various versions of 102the current active Yocto Project releases. 103 104Transition pages have been added (as rst files) to show links to old 105versions of the Yocto Project documentation with links to each manual 106generated with DocBook. 107 108How to build the Yocto Project documentation 109============================================ 110 111Sphinx is written in Python. While it might work with Python2, for 112obvious reasons, we will only support building the Yocto Project 113documentation with Python3. 114 115Sphinx might be available in your Linux distro packages repositories, 116however it is not recommended to use distro packages, as they might be 117old versions, especially if you are using an LTS version of your 118distro. The recommended method to install the latest versions of Sphinx 119and of its required dependencies is to use the Python Package Index (pip). 120 121To install all required packages run: 122 123 $ pip3 install sphinx sphinx_rtd_theme pyyaml 124 125To make sure you always have the latest versions of such packages, you 126should regularly run the same command with an added "--upgrade" option: 127 128 $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml 129 130Also install the "inkscape" package from your distribution. 131Inkscape is need to convert SVG graphics to PNG (for EPUB 132export) and to PDF (for PDF export). 133 134Additionally install "fncychap.sty" TeX font if you want to build PDFs. Debian 135and Ubuntu have it in "texlive-latex-extra" package while RedHat distributions 136and OpenSUSE have it in "texlive-fncychap" package for example. 137 138To build the documentation locally, run: 139 140 $ cd documentation 141 $ make html 142 143The resulting HTML index page will be _build/html/index.html, and you 144can browse your own copy of the locally generated documentation with 145your browser. 146 147Alternatively, you can use Pipenv to automatically install all required 148dependencies in a virtual environment: 149 150 $ cd documentation 151 $ pipenv install 152 $ pipenv run make html 153 154Sphinx theme and CSS customization 155================================== 156 157The Yocto Project documentation is currently based on the "Read the 158Docs" Sphinx theme, with a few changes to make sure the look and feel 159of the project documentation is preserved. 160 161Most of the theme changes can be done using the file 162'sphinx-static/theme_overrides.css'. Most CSS changes in this file 163were inherited from the DocBook CSS stylesheets. 164 165Sphinx design guidelines and principles 166======================================= 167 168The initial Docbook to Sphinx migration was done with an automated 169tool called Pandoc (https://pandoc.org/). The tool produced some clean 170output markdown text files. After the initial automated conversion 171additional changes were done to fix up headings, images and links. In 172addition Sphinx has built in mechanisms (directives) which were used 173to replace similar functions implemented in Docbook such as glossary, 174variables substitutions, notes and references. 175 176Headings 177======== 178 179The layout of the Yocto Project manuals is organized as follows 180 181 Book 182 Chapter 183 Section 184 Subsection 185 Subsubsection 186 Subsubsubsection 187 188Here are the heading styles that we use in the manuals: 189 190 Book => overline === 191 Chapter => overline *** 192 Section => ==== 193 Subsection => ---- 194 Subsubsection => ~~~~ 195 Subsubsubsection => ^^^^ 196 197With this proposal, we preserve the same TOCs between Sphinx and Docbook. 198 199Built-in glossary 200================= 201 202Sphinx has a glossary directive. From 203https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary: 204 205 This directive must contain a reST definition list with terms and 206 definitions. It's then possible to refer to each definition through the 207 [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term 208 'term' role]. 209 210So anywhere in any of the Yocto Project manuals, :term:`VAR` can be 211used to refer to an item from the glossary, and a link is created 212automatically. A general index of terms is also generated by Sphinx 213automatically. 214 215Global substitutions 216==================== 217 218The Yocto Project documentation makes heavy use of global 219variables. In Docbook these variables are stored in the file 220poky.ent. This Docbook feature is not handled automatically with 221Pandoc. Sphinx has builtin support for substitutions 222(https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions), 223however there are important shortcomings. For example they cannot be 224used/nested inside code-block sections. 225 226A Sphinx extension was implemented to support variable substitutions 227to mimic the DocBook based documentation behavior. Variable 228substitutions are done while reading/parsing the .rst files. The 229pattern for variables substitutions is the same as with DocBook, 230e.g. `&VAR;`. 231 232The implementation of the extension can be found here in the file 233documentation/sphinx/yocto-vars.py, this extension is enabled by 234default when building the Yocto Project documentation. All variables 235are set in a file call poky.yaml, which was initially generated from 236poky.ent. The file was converted into YAML so that it is easier to 237process by the custom Sphinx extension (which is a Python module). 238 239For example, the following .rst content will produce the 'expected' 240content: 241 242 .. code-block:: 243 $ mkdir poky-&DISTRO; 244 or 245 $ git clone &YOCTO_GIT_URL;/git/poky -b &DISTRO_NAME_NO_CAP; 246 247Variables can be nested, like it was the case for DocBook: 248 249 YOCTO_HOME_URL : "https://www.yoctoproject.org" 250 YOCTO_DOCS_URL : "&YOCTO_HOME_URL;/docs" 251 252Note directive 253============== 254 255Sphinx has a builtin 'note' directive that produces clean Note section 256in the output file. There are various types of directives such as 257"attention", "caution", "danger", "error", "hint", "important", "tip", 258"warning", "admonition" that are supported, and additional directives 259can be added as Sphinx extension if needed. 260 261Figures 262======= 263 264The Yocto Project documentation has many figures/images. Sphinx has a 265'figure' directive which is straightforward to use. To include a 266figure in the body of the documentation: 267 268 .. image:: figures/YP-flow-diagram.png 269 270Links and References 271==================== 272 273The following types of links can be used: links to other locations in 274the same document, to locations in other documents and to external 275websites. 276 277More information can be found here: 278https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html. 279 280For external links, we use this syntax: 281`link text <link URL>`__ 282 283instead of: 284`link text <link URL>`_ 285 286Both syntaxes work, but the latter also creates a "link text" reference 287target which could conflict with other references with the same name. 288So, only use this variant when you wish to make multiple references 289to this link, reusing only the target name. 290 291See https://stackoverflow.com/questions/27420317/restructured-text-rst-http-links-underscore-vs-use 292 293Anchor (<#link>) links are forbidden as they are not checked by Sphinx during 294the build and may be broken without knowing about it. 295 296References 297========== 298 299The following extension is enabled by default: 300sphinx.ext.autosectionlabel 301(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html). 302 303This extension allows you to refer sections by their titles. Note that 304autosectionlabel_prefix_document is enabled by default, so that we can 305insert references from any document. 306 307For example, to insert an HTML link to a section from 308documentation/manual/intro.rst, use: 309 310 Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document` 311 312Alternatively a custom text can be used instead of using the section 313text: 314 315 Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>` 316 317TIP: The following command can be used to dump all the references that 318 are defined in the project documentation: 319 320 python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv 321 322This dump contains all links and for each link it shows the default 323"Link Text" that Sphinx would use. If the default link text is not 324appropriate, a custom link text can be used in the ':ref:' directive. 325 326Extlinks 327======== 328 329The sphinx.ext.extlinks extension is enabled by default 330(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension), 331and it is configured with the 'extlinks' definitions in 332the 'documentation/conf.py' file: 333 334 'yocto_home': ('https://yoctoproject.org%s', None), 335 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None), 336 'yocto_dl': ('https://downloads.yoctoproject.org%s', None), 337 'yocto_lists': ('https://lists.yoctoproject.org%s', None), 338 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None), 339 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None), 340 'yocto_docs': ('https://docs.yoctoproject.org%s', None), 341 'yocto_git': ('https://git.yoctoproject.org%s', None), 342 'oe_home': ('https://www.openembedded.org%s', None), 343 'oe_lists': ('https://lists.openembedded.org%s', None), 344 'oe_git': ('https://git.openembedded.org%s', None), 345 'oe_wiki': ('https://www.openembedded.org/wiki%s', None), 346 'oe_layerindex': ('https://layers.openembedded.org%s', None), 347 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None), 348 349It creates convenient shortcuts which can be used throughout the 350documentation rst files, as: 351 352 Please check this :yocto_wiki:`wiki page </Weekly_Status>` 353 354Intersphinx links 355================= 356 357The sphinx.ext.intersphinx extension is enabled by default 358(https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html), 359so that we can cross reference content from other Sphinx based 360documentation projects, such as the BitBake manual. 361 362References to the BitBake manual can directly be done: 363 - With a specific description instead of the section name: 364 :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` 365 - With the section name: 366 :ref:`bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option 367 368If you want to refer to an entire document (or chapter) in the BitBake manual, 369you have to use the ":doc:" macro with the "bitbake:" prefix: 370 - :doc:`BitBake User Manual <bitbake:index>` 371 - :doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" chapter 372 373Note that a reference to a variable (:term:`VARIABLE`) automatically points to 374the BitBake manual if the variable is not described in the Reference Manual's Variable Glossary. 375However, if you need to bypass this, you can explicitely refer to a description in the 376BitBake manual as follows: 377 378 :term:`bitbake:BB_NUMBER_PARSE_THREADS` 379 380This would be the same if we had identical document filenames in 381both the Yocto Project and BitBake manuals: 382 383 :ref:`bitbake:directory/file:section title` 384 385Submitting documentation changes 386================================ 387 388Please see the top level README file in this repository for details of where 389to send patches. 390