blob: 2a017569f7ffb37066b15ce0039edf1edc7d386b [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001# Configuration file for the Sphinx documentation builder.
2#
Andrew Geisslerf0343792020-11-18 10:42:21 -06003# SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004#
5# This file only contains a selection of the most common options. For a full
6# list see the documentation:
7# https://www.sphinx-doc.org/en/master/usage/configuration.html
8
9# -- Path setup --------------------------------------------------------------
10
11# If extensions (or modules to document with autodoc) are in another directory,
12# add these directories to sys.path here. If the directory is relative to the
13# documentation root, use os.path.abspath to make it absolute, like shown here.
14#
15import os
16import sys
17import datetime
Andrew Geissler9aee5002022-03-30 16:27:02 +000018try:
19 import yaml
20except ImportError:
21 sys.stderr.write("The Yocto Project Sphinx documentation requires PyYAML.\
Andrew Geisslerd5838332022-05-27 11:33:10 -050022 \nPlease make sure to install pyyaml Python package.\n")
Andrew Geissler9aee5002022-03-30 16:27:02 +000023 sys.exit(1)
Andrew Geisslerc9f78652020-09-18 14:11:35 -050024
Andrew Geissler9aee5002022-03-30 16:27:02 +000025# current_version = "dev"
26# bitbake_version = "" # Leave empty for development branch
27# Obtain versions from poky.yaml instead
28with open("poky.yaml") as data:
29 buff = data.read()
30 subst_vars = yaml.safe_load(buff)
31 if "DOCCONF_VERSION" not in subst_vars:
32 sys.stderr.write("Please set DOCCONF_VERSION in poky.yaml")
33 sys.exit(1)
34 current_version = subst_vars["DOCCONF_VERSION"]
35 if "BITBAKE_SERIES" not in subst_vars:
36 sys.stderr.write("Please set BITBAKE_SERIES in poky.yaml")
37 sys.exit(1)
38 bitbake_version = subst_vars["BITBAKE_SERIES"]
Andrew Geisslerc9f78652020-09-18 14:11:35 -050039
40# String used in sidebar
41version = 'Version: ' + current_version
42if current_version == 'dev':
43 version = 'Version: Current Development'
44# Version seen in documentation_options.js and hence in js switchers code
45release = current_version
46
47
48# -- Project information -----------------------------------------------------
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050049project = 'The Yocto Project \xae'
Patrick Williams0ca19cc2021-08-16 14:03:13 -050050copyright = '2010-%s, The Linux Foundation, CC-BY-SA-2.0-UK license' % datetime.datetime.now().year
Andrew Geisslerc9f78652020-09-18 14:11:35 -050051author = 'The Linux Foundation'
52
53# -- General configuration ---------------------------------------------------
54
Andrew Geisslerd1e89492021-02-12 15:35:20 -060055# Prevent building with an outdated version of sphinx
Andrew Geissler615f2f12022-07-15 14:00:58 -050056needs_sphinx = "4.0"
Andrew Geisslerd1e89492021-02-12 15:35:20 -060057
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058# to load local extension from the folder 'sphinx'
59sys.path.insert(0, os.path.abspath('sphinx'))
60
61# Add any Sphinx extension module names here, as strings. They can be
62# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
63# ones.
64extensions = [
65 'sphinx.ext.autosectionlabel',
66 'sphinx.ext.extlinks',
67 'sphinx.ext.intersphinx',
68 'yocto-vars'
69]
70autosectionlabel_prefix_document = True
71
72# Add any paths that contain templates here, relative to this directory.
73templates_path = ['_templates']
74
75# List of patterns, relative to source directory, that match files and
76# directories to ignore when looking for source files.
77# This pattern also affects html_static_path and html_extra_path.
Andrew Geissler6ce62a22020-11-30 19:58:47 -060078exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'boilerplate.rst']
Andrew Geisslerc9f78652020-09-18 14:11:35 -050079
80# master document name. The default changed from contents to index. so better
81# set it ourselves.
82master_doc = 'index'
83
84# create substitution for project configuration variables
85rst_prolog = """
86.. |project_name| replace:: %s
87.. |copyright| replace:: %s
88.. |author| replace:: %s
89""" % (project, copyright, author)
90
91# external links and substitutions
92extlinks = {
Andrew Geissler615f2f12022-07-15 14:00:58 -050093 'cve': ('https://nvd.nist.gov/vuln/detail/CVE-%s', 'CVE-%s'),
Andrew Geisslerd1e89492021-02-12 15:35:20 -060094 'yocto_home': ('https://www.yoctoproject.org%s', None),
Andrew Geissler09209ee2020-12-13 08:44:15 -060095 'yocto_wiki': ('https://wiki.yoctoproject.org/wiki%s', None),
Andrew Geisslerc9f78652020-09-18 14:11:35 -050096 'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
97 'yocto_lists': ('https://lists.yoctoproject.org%s', None),
98 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
99 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
100 'yocto_docs': ('https://docs.yoctoproject.org%s', None),
Andrew Geissler09209ee2020-12-13 08:44:15 -0600101 'yocto_git': ('https://git.yoctoproject.org/cgit/cgit.cgi%s', None),
Andrew Geisslereff27472021-10-29 15:35:00 -0500102 'yocto_sstate': ('http://sstate.yoctoproject.org%s', None),
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500103 'oe_home': ('https://www.openembedded.org%s', None),
104 'oe_lists': ('https://lists.openembedded.org%s', None),
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600105 'oe_git': ('https://git.openembedded.org%s', None),
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600106 'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
107 'oe_layerindex': ('https://layers.openembedded.org%s', None),
108 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500109}
110
Andrew Geisslerd5838332022-05-27 11:33:10 -0500111# Intersphinx config to use cross reference with BitBake user manual
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500112intersphinx_mapping = {
Andrew Geissler595f6302022-01-24 19:11:47 +0000113 'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114}
115
Andrew Geissler09036742021-06-25 14:25:14 -0500116# Suppress "WARNING: unknown mimetype for ..."
117suppress_warnings = ['epub.unknown_project_files']
118
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500119# -- Options for HTML output -------------------------------------------------
120
121# The theme to use for HTML and HTML Help pages. See the documentation for
122# a list of builtin themes.
123#
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500124try:
125 import sphinx_rtd_theme
126 html_theme = 'sphinx_rtd_theme'
127 html_theme_options = {
128 'sticky_navigation': False,
129 }
130except ImportError:
131 sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
Andrew Geisslerd5838332022-05-27 11:33:10 -0500132 \nPlease make sure to install the sphinx_rtd_theme Python package.\n")
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500133 sys.exit(1)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500134
135html_logo = 'sphinx-static/YoctoProject_Logo_RGB.jpg'
136
137# Add any paths that contain custom static files (such as style sheets) here,
138# relative to this directory. They are copied after the builtin static files,
139# so a file named "default.css" will overwrite the builtin "default.css".
140html_static_path = ['sphinx-static']
141
142html_context = {
143 'current_version': current_version,
144}
145
146# Add customm CSS and JS files
147html_css_files = ['theme_overrides.css']
148html_js_files = ['switchers.js']
149
150# Hide 'Created using Sphinx' text
151html_show_sphinx = False
152
153# Add 'Last updated' on each page
154html_last_updated_fmt = '%b %d, %Y'
155
156# Remove the trailing 'dot' in section numbers
157html_secnumber_suffix = " "
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600158
159latex_elements = {
160 'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
161 'preamble': '\setcounter{tocdepth}{2}',
162}
Andrew Geisslereff27472021-10-29 15:35:00 -0500163
164# Make the EPUB builder prefer PNG to SVG because of issues rendering Inkscape SVG
165from sphinx.builders.epub3 import Epub3Builder
166Epub3Builder.supported_image_types = ['image/png', 'image/gif', 'image/jpeg']