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