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 'cve_mitre': ('https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s', 'CVE-%s'), 95 'yocto_home': ('https://www.yoctoproject.org%s', None), 96 'yocto_wiki': ('https://wiki.yoctoproject.org/wiki%s', None), 97 'yocto_dl': ('https://downloads.yoctoproject.org%s', None), 98 'yocto_lists': ('https://lists.yoctoproject.org%s', None), 99 'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None), 100 'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None), 101 'yocto_docs': ('https://docs.yoctoproject.org%s', None), 102 'yocto_git': ('https://git.yoctoproject.org%s', None), 103 'yocto_sstate': ('http://sstate.yoctoproject.org%s', None), 104 'oe_home': ('https://www.openembedded.org%s', None), 105 'oe_lists': ('https://lists.openembedded.org%s', None), 106 'oe_git': ('https://git.openembedded.org%s', None), 107 'oe_wiki': ('https://www.openembedded.org/wiki%s', None), 108 'oe_layerindex': ('https://layers.openembedded.org%s', None), 109 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None), 110 'wikipedia': ('https://en.wikipedia.org/wiki/%s', None), 111} 112 113# Intersphinx config to use cross reference with BitBake user manual 114intersphinx_mapping = { 115 'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None) 116} 117 118# Suppress "WARNING: unknown mimetype for ..." 119suppress_warnings = ['epub.unknown_project_files'] 120 121# -- Options for HTML output ------------------------------------------------- 122 123# The theme to use for HTML and HTML Help pages. See the documentation for 124# a list of builtin themes. 125# 126try: 127 import sphinx_rtd_theme 128 html_theme = 'sphinx_rtd_theme' 129 html_theme_options = { 130 'sticky_navigation': False, 131 } 132except ImportError: 133 sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\ 134 \nPlease make sure to install the sphinx_rtd_theme Python package.\n") 135 sys.exit(1) 136 137html_logo = 'sphinx-static/YoctoProject_Logo_RGB.jpg' 138 139# Add any paths that contain custom static files (such as style sheets) here, 140# relative to this directory. They are copied after the builtin static files, 141# so a file named "default.css" will overwrite the builtin "default.css". 142html_static_path = ['sphinx-static'] 143 144html_context = { 145 'current_version': current_version, 146} 147 148# Add customm CSS and JS files 149html_css_files = ['theme_overrides.css'] 150html_js_files = ['switchers.js'] 151 152# Hide 'Created using Sphinx' text 153html_show_sphinx = False 154 155# Add 'Last updated' on each page 156html_last_updated_fmt = '%b %d, %Y' 157 158# Remove the trailing 'dot' in section numbers 159html_secnumber_suffix = " " 160 161latex_elements = { 162 'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}', 163 'preamble': '\setcounter{tocdepth}{2}', 164} 165 166# Make the EPUB builder prefer PNG to SVG because of issues rendering Inkscape SVG 167from sphinx.builders.epub3 import Epub3Builder 168Epub3Builder.supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] 169