summaryrefslogtreecommitdiffstats
path: root/documentation/conf.py
Commit message (Collapse)AuthorAgeFilesLines
* sphinx: report errors when dependencies are not metNicolas Dechesne2020-09-221-4/+10
| | | | | | | | | | | | | | | | 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>
* sphinx: conf: exclude adt-manual/*.rstNicolas Dechesne2020-09-171-1/+2
| | | | | | | | | | | 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>
* sphinx: conf: include CSS/JS files, the proper wayNicolas Dechesne2020-09-171-3/+4
| | | | | | | | | | | 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>
* sphinx: conf: a few rendering tweaksNicolas Dechesne2020-09-171-0/+12
| | | | | | | | | | | * 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>
* sphinx: Add support for multiple docs versionRichard Purdie2020-09-171-5/+13
| | | | | | | | | | | | 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>
* sphinx: enable intersphinx extensionNicolas Dechesne2020-09-171-0/+6
| | | | | | | | | | | 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>
* sphinx: setup extlink for docs.yoctoproject.orgNicolas Dechesne2020-09-171-0/+1
| | | | | | | (From yocto-docs rev: ec5c86368b90e4fb92295780fb10cf29c66c0fb4) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
* sphinx: conf.py: enable sphinx.ext.autosectionlabelNicolas Dechesne2020-09-171-0/+2
| | | | | | | | | | 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>
* sphinx: add boilerplate fileNicolas Dechesne2020-09-171-1/+1
| | | | | | | | | | | | 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>
* sphinx: conf: add substitutions/global variablesNicolas Dechesne2020-09-171-0/+25
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* sphinx: conf: update copyrightNicolas Dechesne2020-09-171-2/+2
| | | | | | | (From yocto-docs rev: 9a5c74f73f2f00d8dbd3bc4f72973f9e2913b316) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
* sphinx: add Yocto project logoNicolas Dechesne2020-09-171-0/+2
| | | | | | | (From yocto-docs rev: 125c70b04a28bf095ed1cd8273ebdc7d1d0b5cfd) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
* sphinx: add CSS theme overrideNicolas Dechesne2020-09-171-1/+7
| | | | | | | | | | | | | | | 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>
* sphinx: Add SPDX license headersNicolas Dechesne2020-09-171-0/+2
| | | | | | | | | | 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>
* sphinx: switch to readthedocs themeNicolas Dechesne2020-09-171-1/+1
| | | | | | | | | | 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>
* sphinx: add initial build infrastructureNicolas Dechesne2020-09-171-0/+55
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>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-22 12:50:49 +0000