Commit Graph

32 Commits

Author SHA1 Message Date
Michael Opdenacker
b8f5107e26 documentation: conf.py: fix version of bitbake objects.inv
Using the Bitbake 1.50 references instead of the master ones,
which may break if some variables or sections are removed.

(From yocto-docs rev: 79e90a28ef7f591b1b9b4c41ef7f353bcf17679f)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2021-12-09 00:18:44 +00:00
Anuj Mittal
507c32b9d7 documentation: prepare for 3.3.4 release
Also add a link for documentation to just released 3.1.11 release.

(From yocto-docs rev: e8e4539e1e812ea835192d1e35cc9992a43059ca)

Signed-off-by: Anuj Mittal <anuj.mittal@intel.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2021-11-03 11:31:27 +00:00
Anuj Mittal
52994ada6e documentation: prepare for 3.3.3 release
Also add a link for documentation to just release 3.1.10 release.

(From yocto-docs rev: d890e8fcf0c43ea911c04e84b80c250432236010)

Signed-off-by: Anuj Mittal <anuj.mittal@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2021-09-01 16:28:04 +01:00
Anuj Mittal
f3014b1bbb documentation: prepare for 3.3.2 release
Include updates to versions for dunfell releases as well.

(From yocto-docs rev: dae6a0209d69c267d3cbace6589b0ac73e06abce)

Signed-off-by: Anuj Mittal <anuj.mittal@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2021-07-20 19:07:26 +01:00
Richard Purdie
05a8aad57c documentation: prepare for 3.3.1 release
Include update to previous releases.

(From yocto-docs rev: eb19a2b5687f11c22c7fc26d3efabbf65adb572e)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2021-05-17 09:47:53 +01:00
Yoann Congal
164db40a72 documentation: Prevent building documentation with an outdated version of sphinx
Building with a outdated version of Sphinx print warnings that does not
appear on up-to-date sphinx.

This patch prevent building the documentation with any version older
than 3.1 (First version to build without warnings in my tests)

See threads "documentation: Add a simple Sphinx extension to check its version"
    https://lists.yoctoproject.org/g/docs/topic/patch_documentation_add_a/79919516
and "toaster-manual: Fix a warning related to the code-block directive"
    https://lists.yoctoproject.org/g/docs/topic/patch_toaster_manual_fix_a/79656195

(From yocto-docs rev: 4de0f3dd4d5df0a0700f704a599bb41726d15a5f)

Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2021-01-20 00:53:53 +00:00
Paul Barker
58892e05f6 documentation: Simplify remaining yocto_home links
(From yocto-docs rev: e0151e039f96c1548e2ec39ae24d4b0276f49434)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-12-24 08:23:33 +00:00
Paul Barker
ddf55dca6b documentation: Simplify layerindex and layer links
(From yocto-docs rev: b157d57cc50b0a9cfaa062fa0e966b4d29eceeec)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-12-24 08:23:33 +00:00
Paul Barker
d903e586c2 documentation: Simplify oe_wiki and oe_home links
(From yocto-docs rev: 6867f54f349edede37c4085194f51342c24297ed)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-12-24 08:23:33 +00:00
Paul Barker
48748377a4 documentation: Simplify yocto_git links
The yocto_git external link directive is modified to include the
`/cgit/cgit.cgi` element of the URL so that we can simplify the links in
the text.

Manual links to git.yoctoproject.org are converted to use the yocto_git
directive where possible. Note that this directive can't be used in some
places such as example code.

(From yocto-docs rev: 3a8ba5dcc783411c73fe49fb217cbc4d6528d9a7)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-12-03 12:04:21 +00:00
Paul Barker
8faafa99cc documentation: Simplify yocto_wiki links
The `yocto_wiki` external link directive is modified to include the
`/wiki` element of the URL so that we can simplify the links in the
text.

Note that there are still a couple of places where this directive
cannot be used, such as in the table of contents in index.rst.

(From yocto-docs rev: d8aa5f93d349f27db3d03a2c4bcc205649f45a8d)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-12-03 12:04:21 +00:00
Paul Barker
5c6f5a8f98 conf.py: Add oe_git directive
This simplifies linking to git repositories on openembedded.org.

(From yocto-docs rev: 03e13ca4d013e7712216a66eb4cdeb4a456be6a9)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-11-20 14:32:25 +00:00
Paul Barker
52c71e41d4 conf.py: Improve TOC and Outline depth in PDF output
The default PDF output shows only chapter headings in the table of
contents and in the outline (aka PDF bookmarks). We should override
these defaults to set something more suitable.

With a depth of 2 for the TOC we see both section and subsection
headings which is enough to get the list of classes in the reference
manual and the list of topics under "Common Tasks" in the development
manual. Going to a deeper level would make the TOC unwieldy but we do
want to make sure we can navigate more precisely using the outline
(commonly shown in a left tab in PDF viewers) so we set the depth to 5
for the outline.

(From yocto-docs rev: 5db16d3b01da0a138b6413347fcf2321a1bfae08)

Signed-off-by: Paul Barker <pbarker@konsulko.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-11-13 14:36:51 +00:00
Robert P. J. Day
43e3a19c19 adt-manual: delete obsolete ADT manual, and related content
Since the ADT manual has long been superseded by the SDK manual,
remove the entire adt-manual directory, and the references to it in
the two top-level files "conf.py" and "poky.yaml".

(From yocto-docs rev: 64b2e83bddf6af0439ac7089ac95e60faa696cfc)

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-10-30 16:03:19 +00:00
Richard Purdie
fe74a4edd2 docs: Fix license CC-BY-2.0-UK -> CC-BY-SA-2.0-UK
When the license identifier tags were added, an incorrect string was used
and the Share-Alike clause was lost. Fix this to match the license
description in the files and add back the lost piece (its clear from
the history it should be there)

(From yocto-docs rev: 8d30c3d792755a7bfdb74b331dad98f51d3516af)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-10-08 11:28:30 +01:00
Nicolas Dechesne
b23aa6b753 sphinx: fix up some trademark and branding issues
The following changes were required after a review of trademark and
branding guidelines:

1. add (R) to 'Yocto Project' on the top left (above the logo)
2. Fix up the capitalization of the  main page title
3. Add the copyright/legal blurb at the bottom of the page

For 3. it turned out to be simpler to override the whole footer.html
template, and maintain our own version. Also I took the liberty to
remove the 'next' and 'previous' buttons since I believe they are not
especially useful, given the navigation bar on the left side.

Reported-by: Tracey Erway <tracey.m.erway@intel.com>
(From yocto-docs rev: 6bae1372218e0b10258e4fa6fef72fc1708a329c)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-10-01 21:29:31 +01:00
Nicolas Dechesne
a69d74c842 sphinx: report errors when dependencies are not met
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>
2020-09-22 09:58:50 +01:00
Nicolas Dechesne
0ce3f64fce sphinx: conf: exclude adt-manual/*.rst
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>
2020-09-17 10:09:35 +01:00
Nicolas Dechesne
e4b904b21c sphinx: conf: include CSS/JS files, the proper way
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>
2020-09-17 10:09:34 +01:00
Nicolas Dechesne
8fbaa0331c sphinx: conf: a few rendering tweaks
* 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>
2020-09-17 10:09:34 +01:00
Richard Purdie
ad2e3e6146 sphinx: Add support for multiple docs version
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>
2020-09-17 10:09:34 +01:00
Nicolas Dechesne
18a484df63 sphinx: enable intersphinx extension
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>
2020-09-17 10:09:34 +01:00
Nicolas Dechesne
4b3766b0db sphinx: setup extlink for docs.yoctoproject.org
(From yocto-docs rev: ec5c86368b90e4fb92295780fb10cf29c66c0fb4)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-09-17 10:09:34 +01:00
Nicolas Dechesne
303f1a9ef7 sphinx: conf.py: enable sphinx.ext.autosectionlabel
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>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
54d38a91e1 sphinx: add boilerplate file
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>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
44e8d439aa sphinx: conf: add substitutions/global variables
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>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
18786fbffe sphinx: conf: update copyright
(From yocto-docs rev: 9a5c74f73f2f00d8dbd3bc4f72973f9e2913b316)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
fd71ce03e9 sphinx: add Yocto project logo
(From yocto-docs rev: 125c70b04a28bf095ed1cd8273ebdc7d1d0b5cfd)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
2c3298d72e sphinx: add CSS theme override
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>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
7ea70a656b sphinx: Add SPDX license headers
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>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
6c445d85f0 sphinx: switch to readthedocs theme
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>
2020-09-17 10:09:33 +01:00
Nicolas Dechesne
c40a8d5904 sphinx: add initial build infrastructure
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>
2020-09-17 10:09:32 +01:00