123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327 |
- documentation
- =============
- This is the directory that contains the Yocto Project documentation. The Yocto
- Project source repositories at http://git.yoctoproject.org/cgit.cgi have two
- instances of the "documentation" directory. You should understand each of
- these instances.
- poky/documentation - The directory within the poky Git repository containing
- the set of Yocto Project manuals. When you clone the
- poky Git repository, the documentation directory
- contains the manuals. The state of the manuals in this
- directory is guaranteed to reflect the latest Yocto
- Project release. The manuals at the tip of this
- directory will also likely contain most manual
- development changes.
- yocto-docs/documentation - The Git repository for the Yocto Project manuals.
- This repository is where manual development
- occurs. If you plan on contributing back to the
- Yocto Project documentation, you should set up
- a local Git repository based on this upstream
- repository as follows:
- git clone git://git.yoctoproject.org/yocto-docs
- Changes and patches are first pushed to the
- yocto-docs Git repository. Later, they make it
- into the poky Git repository found at
- git://git.yoctoproject.org/poky.
- Manual Organization
- ===================
- Folders exist for individual manuals as follows:
- * sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide.
- * bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide
- * dev-manual - The Yocto Project Development Tasks Manual
- * kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual
- * ref-manual - The Yocto Project Reference Manual
- * brief-yoctoprojectqs - The Yocto Project Quick Start
- * profile-manual - The Yocto Project Profile and Tracing Manual
- * toaster-manual - The Toaster Manual
- * test-manual - The Test Environment Manual
- Each folder is self-contained regarding content and figures.
- If you want to find HTML versions of the Yocto Project manuals on the web,
- go to http://www.yoctoproject.org and click on the "Documentation" tab. From
- there you have access to archived documentation from previous releases, current
- documentation for the latest release, and "Docs in Progress" for the release
- currently being developed.
- In general, the Yocto Project site (http://www.yoctoproject.org) is a great
- reference for both information and downloads.
- poky.yaml
- =========
- This file defines variables used for documentation production. The variables
- are used to define release pathnames, URLs for the published manuals, etc.
- template
- ========
- Contains various templates, fonts, and some old PNG files.
- Sphinx
- ======
- The Yocto Project documentation was migrated from the original DocBook
- format to Sphinx based documentation for the Yocto Project 3.2
- release. This section will provide additional information related to
- the Sphinx migration, and guidelines for developers willing to
- contribute to the Yocto Project documentation.
- Sphinx is a tool that makes it easy to create intelligent and
- beautiful documentation, written by Georg Brandl and licensed under
- the BSD license. It was originally created for the Python
- documentation.
- Extensive documentation is available on the Sphinx website:
- https://www.sphinx-doc.org/en/master/. Sphinx is designed to be
- extensible thanks to the ability to write our own custom extensions,
- as Python modules, which will be executed during the generation of the
- documentation.
- Yocto Project documentation website
- ===================================
- A new website has been created to host the Yocto Project
- documentation, it can be found at: https://docs.yoctoproject.org/.
- The entire Yocto Project documentation, as well as the BitBake manual
- is published on this website, including all previously released
- versions. A version switcher was added, as a drop-down menu on the top
- of the page to switch back and forth between the various versions of
- the current active Yocto Project releases.
- Transition pages have been added (as rst file) to show links to old
- versions of the Yocto Project documentation with links to each manual
- generated with DocBook.
- How to build the Yocto Project documentation
- ============================================
- Sphinx is written in Python. While it might work with Python2, for
- obvious reasons, we will only support building the Yocto Project
- documentation with Python3.
- Sphinx might be available in your Linux distro packages repositories,
- however it is not recommend using distro packages, as they might be
- old versions, especially if you are using an LTS version of your
- distro. The recommended method to install Sphinx and all required
- dependencies is to use the Python Package Index (pip).
- To install all required packages run:
- $ pip3 install sphinx sphinx_rtd_theme pyyaml
- To build the documentation locally, run:
- $ cd documentation
- $ make html
- The resulting HTML index page will be _build/html/index.html, and you
- can browse your own copy of the locally generated documentation with
- your browser.
- Alternatively, you can use Pipenv to automatically install all required
- dependencies in a virtual environment:
- $ cd documentation
- $ pipenv install
- $ pipenv run make html
- Sphinx theme and CSS customization
- ==================================
- The Yocto Project documentation is currently based on the "Read the
- Docs" Sphinx theme, with a few changes to make sure the look and feel
- of the project documentation is preserved.
- Most of the theme changes can be done using the file
- 'sphinx-static/theme_overrides.css'. Most CSS changes in this file
- were inherited from the DocBook CSS stylesheets.
- Sphinx design guidelines and principles
- =======================================
- The initial Docbook to Sphinx migration was done with an automated
- tool called Pandoc (https://pandoc.org/). The tool produced some clean
- output markdown text files. After the initial automated conversion
- additional changes were done to fix up headings, images and links. In
- addition Sphinx has built in mechanisms (directives) which were used
- to replace similar functions implemented in Docbook such as glossary,
- variables substitutions, notes and references.
- Headings
- ========
- The layout of the Yocto Project manuals is organized as follows
- Book
- Chapter
- Section
- Section
- Section
- The following headings styles are defined in Sphinx:
- Book => overline ===
- Chapter => overline ***
- Section => ====
- Section => ----
- Section => ^^^^
- Section => """" or ~~~~
- With this proposal, we preserve the same TOCs between Sphinx and Docbook.
- Built-in glossary
- =================
- Sphinx has a glossary directive. From
- https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary:
- This directive must contain a reST definition list with terms and
- definitions. The definitions will then be referencable with the
- [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term
- 'term' role].
- So anywhere in any of the Yocto Project manuals, :term:`VAR` can be
- used to refer to an item from the glossary, and a link is created
- automatically. A general index of terms is also generated by Sphinx
- automatically.
- Global substitutions
- ====================
- The Yocto Project documentation makes heavy use of global
- variables. In Docbook these variables are stored in the file
- poky.ent. This Docbook feature is not handled automatically with
- Pandoc. Sphinx has builtin support for substitutions
- (https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions),
- however there are important shortcomings. For example they cannot be
- used/nested inside code-block sections.
- A Sphinx extension was implemented to support variable substitutions
- to mimic the DocBook based documentation behavior. Variabes
- substitutions are done while reading/parsing the .rst files. The
- pattern for variables substitutions is the same as with DocBook,
- e.g. `&VAR;`.
- The implementation of the extension can be found here in the file
- documentation/sphinx/yocto-vars.py, this extension is enabled by
- default when building the Yocto Project documentation. All variables
- are set in a file call poky.yaml, which was initially generated from
- poky.ent. The file was converted into YAML so that it is easier to
- process by the custom Sphinx extension (which is a Python module).
- For example, the following .rst content will produce the 'expected'
- content:
- .. code-block::
- $ mkdir ~/poky-&DISTRO;
- or
- $ git clone &YOCTO_GIT_URL;/git/poky -b &DISTRO_NAME_NO_CAP;
- Variables can be nested, like it was the case for DocBook:
- YOCTO_HOME_URL : "http://www.yoctoproject.org"
- YOCTO_DOCS_URL : "&YOCTO_HOME_URL;/docs"
- Note directive
- ==============
- Sphinx has a builtin 'note' directive that produces clean Note section
- in the output file. There are various types of directives such as
- "attention", "caution", "danger", "error", "hint", "important", "tip",
- "warning", "admonition" that are supported, and additional directive
- can be added as Sphinx extension if needed.
- Figures
- =======
- The Yocto Project documentation has many figures/images. Sphinx has a
- 'figure' directive which is straight forward to use. To include a
- figure in the body of the documentation:
- .. image:: figures/YP-flow-diagram.png
- Links and References
- ====================
- The following types of links can be used: links to other locations in
- the same document, to locations in other documents and to external
- websites.
- More information can be found here:
- https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
- References
- ==========
- The following extension is enabed by default:
- sphinx.ext.autosectionlabel
- (https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html).
- This extension allows you to refer sections by their titles. Note that
- autosectionlabel_prefix_document is enabled by default, so that we can
- insert references from any document.
- For example, to insert an HTML link to a section from
- documentaion/manual/intro.rst, use:
- Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
- Alternatively a custom text can be used instead of using the section
- text:
- Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>`
- TIP: The following command can be used to dump all the references that
- are defined in the project documentation:
- python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv
- This dump contains all links and for each link it shows the default
- "Link Text" that Sphinx would use. If the default link text is not
- appropriate, a custom link text can be used in the ':ref:' directive.
- Extlinks
- ========
- The sphinx.ext.extlinks extension is enabled by default
- (https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension),
- and it is configured with:
- 'yocto_home': ('https://yoctoproject.org%s', None),
- 'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
- 'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
- 'yocto_lists': ('https://lists.yoctoproject.org%s', None),
- 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
- 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
- 'yocto_docs': ('https://docs.yoctoproject.org%s', None),
- 'yocto_git': ('https://git.yoctoproject.org%s', None),
- 'oe_home': ('https://www.openembedded.org%s', None),
- 'oe_lists': ('https://lists.openembedded.org%s', None),
- It creates convenient shortcuts which can be used throughout the
- documentation rst files, as:
- Please check this :yocto_wiki:`wiki page </Weekly_Status>`
- Intersphinx links
- =================
- The sphinx.ext.intersphinx extension is enabled by default
- (https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),
- so that we can cross reference content from other Sphinx based
- documentation projects, such as the BitBake manual.
- References to the bitbake manual can be done like this:
- See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
- or
- :term:`bitbake:BB_NUMBER_PARSE_THREADS`
|