To build the Sphinx documentation, we have the following dependencies:
* sphinx
* sphinx_rtd_theme
* pyyaml
If any of these dependencies are missing, we might end up with some
cryptic error messages. This patch adds better error reporting when
dependencies are not met.
(From yocto-docs rev: 19df8d1ec56dc2ecb44122288cc53e84237fab69)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
The ADT Manual is deprecated, and was removed from the documentation
set in 2.2, until we remove it completely, let's make sure it's
excluded from Sphinx build.
(From yocto-docs rev: 5fa20d6afb1be56cbb2a012357f8ccff4b91d585)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
html_css_files and html_js_files exist since Sphinx 1.8, and it's the
proper (documented) mechanism to include custom CSS and JS files in
the documentation.
(From yocto-docs rev: 4ae9c426654e33fed4185e5d6e0de76b4a430d84)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
* Remove the 'generated by Sphinx' text on each page
* Add a 'last updated timestamp' on each page
* Remove the trailing 'dot' in TOC numbering
(From yocto-docs rev: 3fa6cf149b3dbbd88b3aa75b6ce1f8bd12817c91)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Enhance the sphinx experience/nagivation with:
* Remove the pointless looking parts of breadcrumb navigtation
* Add a document type switcher to the breadcrumb navigation
* Add a version selection switch to the breadcrumb navigation
(From yocto-docs rev: 1823624bdb9ea002d44c9e6d0fd4cd662bff36ad)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This extension can generate automatic links to the documentation of
objects in other projects. We will use it to use cross references with
the Bibtake manual, for example.
(From yocto-docs rev: 5add9854b112f93acba982f237fbfa83aee80d77)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This extension generates the labels for each section, so that we can
reference section by their title.
(From yocto-docs rev: 910bdad33819116f00fd4f849dcf7484fbebb465)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
A certain amount of boilerplate is added at the beginning of all
documents. In DocBook this is copy/pasted in each file. Let's create a
boilerplate ReST file, which we will include in each document,
wherever it's required.
(From yocto-docs rev: 37e0d5f246c614e62a7c0d4d72a5d6ce9ec5325e)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
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 however they are
local to each reST file by default. They can be made global by using
rst_prolog:
rst_prolog
A string of reStructuredText that will be included at the
beginning of every source file that is read.
However Sphinx substitution feature has several important limitations. For
example, substitution does not work in code-block section.
yocto-vars.py is an extension that processes .rst file to find and
replace 'variables'. This plugin will do variables substitutions
whenever a rst file is read, so it happens before sphinx parses the
content.
All variables are set in poky.yaml. It's a simple YAML file with pairs
of variable/value, and the file is parsed once during setup. It's
important to note that variables can reference other
variables. poky.yaml was generated by converting poky.ent into a YAML
format.
To use a variable in the Yocto Project .rst files, make sure it is
defined in poky.yaml, and then you can use : &DISTRO_NAME;
For external links, Sphinx has a specific extension called extlinks,
let's use it instead of variable substituions. Note that we
intentionnally did not put the trailing '/' in the URL, this is to
allow us to use :yocto_git:`/` trick to get the actual URL displayed
in the HTML.
(From yocto-docs rev: dc5f53fae8fdfdda04285869dd1419107b920bfe)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
It is possible to override CSS settings from the theme, by providing
custom snippets of CSS stylesheet. Support for that is added in
conf.py file.
The following changes are made:
* remove the overall text width which (set to 800px by default)
* improve the visual output, and colors of links and admonition
(From yocto-docs rev: 0c1e108bc6c452f7cc8c665bee984bd7da281666)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
SPDX headers have been added to each file, and match the headers used
in the DocBook files.
(From yocto-docs rev: 79dbb0007ae24da4a3689a23e921f2a2638757f7)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
To install this additional theme:
pip3 install sphinx_rtd_theme
(From yocto-docs rev: 9121dbd0a457451d7f7cdffe8fa2717d5e5959ec)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Used sphinx-quickstart to generate top level config and
Makefile.sphinx, to allow side by side DocBook and Sphinx
co-existence.
(From yocto-docs rev: 01dd5af7954e24552aca022917669b27bb0541ed)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
