blob: 8e15fdc869d7a7d509441970bc0f2de4ad54cc0a [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
18
19current_version = "dev"
20
21# String used in sidebar
22version = 'Version: ' + current_version
23if current_version == 'dev':
24 version = 'Version: Current Development'
25# Version seen in documentation_options.js and hence in js switchers code
26release = current_version
27
28
29# -- Project information -----------------------------------------------------
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050030project = 'The Yocto Project \xae'
Patrick Williams0ca19cc2021-08-16 14:03:13 -050031copyright = '2010-%s, The Linux Foundation, CC-BY-SA-2.0-UK license' % datetime.datetime.now().year
Andrew Geisslerc9f78652020-09-18 14:11:35 -050032author = 'The Linux Foundation'
33
34# -- General configuration ---------------------------------------------------
35
Andrew Geisslerd1e89492021-02-12 15:35:20 -060036# Prevent building with an outdated version of sphinx
37needs_sphinx = "3.1"
38
Andrew Geisslerc9f78652020-09-18 14:11:35 -050039# to load local extension from the folder 'sphinx'
40sys.path.insert(0, os.path.abspath('sphinx'))
41
42# Add any Sphinx extension module names here, as strings. They can be
43# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
44# ones.
45extensions = [
46 'sphinx.ext.autosectionlabel',
47 'sphinx.ext.extlinks',
48 'sphinx.ext.intersphinx',
49 'yocto-vars'
50]
51autosectionlabel_prefix_document = True
52
53# Add any paths that contain templates here, relative to this directory.
54templates_path = ['_templates']
55
56# List of patterns, relative to source directory, that match files and
57# directories to ignore when looking for source files.
58# This pattern also affects html_static_path and html_extra_path.
Andrew Geissler6ce62a22020-11-30 19:58:47 -060059exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'boilerplate.rst']
Andrew Geisslerc9f78652020-09-18 14:11:35 -050060
61# master document name. The default changed from contents to index. so better
62# set it ourselves.
63master_doc = 'index'
64
65# create substitution for project configuration variables
66rst_prolog = """
67.. |project_name| replace:: %s
68.. |copyright| replace:: %s
69.. |author| replace:: %s
70""" % (project, copyright, author)
71
72# external links and substitutions
73extlinks = {
Andrew Geisslerd1e89492021-02-12 15:35:20 -060074 'yocto_home': ('https://www.yoctoproject.org%s', None),
Andrew Geissler09209ee2020-12-13 08:44:15 -060075 'yocto_wiki': ('https://wiki.yoctoproject.org/wiki%s', None),
Andrew Geisslerc9f78652020-09-18 14:11:35 -050076 'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
77 'yocto_lists': ('https://lists.yoctoproject.org%s', None),
78 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
79 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
80 'yocto_docs': ('https://docs.yoctoproject.org%s', None),
Andrew Geissler09209ee2020-12-13 08:44:15 -060081 'yocto_git': ('https://git.yoctoproject.org/cgit/cgit.cgi%s', None),
Andrew Geisslerc9f78652020-09-18 14:11:35 -050082 'oe_home': ('https://www.openembedded.org%s', None),
83 'oe_lists': ('https://lists.openembedded.org%s', None),
Andrew Geissler6ce62a22020-11-30 19:58:47 -060084 'oe_git': ('https://git.openembedded.org%s', None),
Andrew Geisslerd1e89492021-02-12 15:35:20 -060085 'oe_wiki': ('https://www.openembedded.org/wiki%s', None),
86 'oe_layerindex': ('https://layers.openembedded.org%s', None),
87 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None),
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088}
89
90# Intersphinx config to use cross reference with Bitbake user manual
91intersphinx_mapping = {
92 'bitbake': ('https://docs.yoctoproject.org/bitbake/', None)
93}
94
Andrew Geissler09036742021-06-25 14:25:14 -050095# Suppress "WARNING: unknown mimetype for ..."
96suppress_warnings = ['epub.unknown_project_files']
97
Andrew Geisslerc9f78652020-09-18 14:11:35 -050098# -- Options for HTML output -------------------------------------------------
99
100# The theme to use for HTML and HTML Help pages. See the documentation for
101# a list of builtin themes.
102#
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500103try:
104 import sphinx_rtd_theme
105 html_theme = 'sphinx_rtd_theme'
106 html_theme_options = {
107 'sticky_navigation': False,
108 }
109except ImportError:
110 sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
111 \nPlease make sure to install the sphinx_rtd_theme python package.\n")
112 sys.exit(1)
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113
114html_logo = 'sphinx-static/YoctoProject_Logo_RGB.jpg'
115
116# Add any paths that contain custom static files (such as style sheets) here,
117# relative to this directory. They are copied after the builtin static files,
118# so a file named "default.css" will overwrite the builtin "default.css".
119html_static_path = ['sphinx-static']
120
121html_context = {
122 'current_version': current_version,
123}
124
125# Add customm CSS and JS files
126html_css_files = ['theme_overrides.css']
127html_js_files = ['switchers.js']
128
129# Hide 'Created using Sphinx' text
130html_show_sphinx = False
131
132# Add 'Last updated' on each page
133html_last_updated_fmt = '%b %d, %Y'
134
135# Remove the trailing 'dot' in section numbers
136html_secnumber_suffix = " "
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600137
138latex_elements = {
139 'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
140 'preamble': '\setcounter{tocdepth}{2}',
141}