1# Configuration file for the Sphinx documentation builder. 2# 3# SPDX-License-Identifier: CC-BY-SA-2.0-UK 4# 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 18try: 19 import yaml 20except ImportError: 21 sys.stderr.write("The Yocto Project Sphinx documentation requires PyYAML.\ 22 \nPlease make sure to install pyyaml Python package.\n") 23 sys.exit(1) 24 25# 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"] 39 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 ----------------------------------------------------- 49project = 'The Yocto Project \xae' 50copyright = '2010-%s, The Linux Foundation, CC-BY-SA-2.0-UK license' % datetime.datetime.now().year 51author = 'The Linux Foundation' 52 53# -- General configuration --------------------------------------------------- 54 55# Prevent building with an outdated version of sphinx 56needs_sphinx = "4.0" 57 58# 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. 78exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'boilerplate.rst'] 79 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 = { 93 'cve': ('https://nvd.nist.gov/vuln/detail/CVE-%s', 'CVE-%s'), 94 'yocto_home': ('https://www.yoctoproject.org%s', None), 95 'yocto_wiki': ('https://wiki.yoctoproject.org/wiki%s', None), 96 '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), 101 'yocto_git': ('https://git.yoctoproject.org%s', None), 102 'yocto_sstate': ('http://sstate.yoctoproject.org%s', None), 103 'oe_home': ('https://www.openembedded.org%s', None), 104 'oe_lists': ('https://lists.openembedded.org%s', None), 105 'oe_git': ('https://git.openembedded.org%s', None), 106 '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), 109 'wikipedia': ('https://en.wikipedia.org/wiki/%s', None), 110} 111 112# Intersphinx config to use cross reference with BitBake user manual 113intersphinx_mapping = { 114 'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None) 115} 116 117# Suppress "WARNING: unknown mimetype for ..." 118suppress_warnings = ['epub.unknown_project_files'] 119 120# -- Options for HTML output ------------------------------------------------- 121 122# The theme to use for HTML and HTML Help pages. See the documentation for 123# a list of builtin themes. 124# 125try: 126 import sphinx_rtd_theme 127 html_theme = 'sphinx_rtd_theme' 128 html_theme_options = { 129 'sticky_navigation': False, 130 } 131except ImportError: 132 sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\ 133 \nPlease make sure to install the sphinx_rtd_theme Python package.\n") 134 sys.exit(1) 135 136html_logo = 'sphinx-static/YoctoProject_Logo_RGB.jpg' 137 138# Add any paths that contain custom static files (such as style sheets) here, 139# relative to this directory. They are copied after the builtin static files, 140# so a file named "default.css" will overwrite the builtin "default.css". 141html_static_path = ['sphinx-static'] 142 143html_context = { 144 'current_version': current_version, 145} 146 147# Add customm CSS and JS files 148html_css_files = ['theme_overrides.css'] 149html_js_files = ['switchers.js'] 150 151# Hide 'Created using Sphinx' text 152html_show_sphinx = False 153 154# Add 'Last updated' on each page 155html_last_updated_fmt = '%b %d, %Y' 156 157# Remove the trailing 'dot' in section numbers 158html_secnumber_suffix = " " 159 160latex_elements = { 161 'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}', 162 'preamble': '\setcounter{tocdepth}{2}', 163} 164 165# Make the EPUB builder prefer PNG to SVG because of issues rendering Inkscape SVG 166from sphinx.builders.epub3 import Epub3Builder 167Epub3Builder.supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] 168