d45079aca1
This is not needed on Python 3.x as it's the default. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
221 lines
6.9 KiB
Python
221 lines
6.9 KiB
Python
# Zephyr documentation build configuration file.
|
|
# Reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
|
|
import sys
|
|
import os
|
|
|
|
from sphinx.highlighting import lexers
|
|
import sphinx_rtd_theme
|
|
|
|
|
|
if "ZEPHYR_BASE" not in os.environ:
|
|
sys.exit("$ZEPHYR_BASE environment variable undefined.")
|
|
ZEPHYR_BASE = os.path.abspath(os.environ["ZEPHYR_BASE"])
|
|
|
|
if "ZEPHYR_BUILD" not in os.environ:
|
|
sys.exit("$ZEPHYR_BUILD environment variable undefined.")
|
|
ZEPHYR_BUILD = os.path.abspath(os.environ["ZEPHYR_BUILD"])
|
|
|
|
# Add the 'extensions' directory to sys.path, to enable finding Sphinx
|
|
# extensions within.
|
|
sys.path.insert(0, os.path.join(ZEPHYR_BASE, 'doc', '_extensions'))
|
|
|
|
# Add the '_scripts' directory to sys.path, to enable finding utility
|
|
# modules.
|
|
sys.path.insert(0, os.path.join(ZEPHYR_BASE, 'doc', '_scripts'))
|
|
|
|
# Add the directory which contains the runners package as well,
|
|
# for autodoc directives on runners.xyz.
|
|
sys.path.insert(0, os.path.join(ZEPHYR_BASE, 'scripts', 'west_commands'))
|
|
|
|
from lexer.DtsLexer import DtsLexer
|
|
import redirects
|
|
|
|
try:
|
|
import west as west_found
|
|
except ImportError:
|
|
west_found = False
|
|
|
|
# -- Project --------------------------------------------------------------
|
|
|
|
project = 'Zephyr Project'
|
|
copyright = '2015-2021 Zephyr Project members and individual contributors'
|
|
author = 'The Zephyr Project'
|
|
|
|
# The following code tries to extract the information by reading the Makefile,
|
|
# when Sphinx is run directly (e.g. by Read the Docs).
|
|
try:
|
|
version_major = None
|
|
version_minor = None
|
|
patchlevel = None
|
|
extraversion = None
|
|
for line in open(os.path.join(ZEPHYR_BASE, 'VERSION')):
|
|
key, val = [x.strip() for x in line.split('=', 2)]
|
|
if key == 'VERSION_MAJOR':
|
|
version_major = val
|
|
if key == 'VERSION_MINOR':
|
|
version_minor = val
|
|
elif key == 'PATCHLEVEL':
|
|
patchlevel = val
|
|
elif key == 'EXTRAVERSION':
|
|
extraversion = val
|
|
if version_major and version_minor and patchlevel and extraversion:
|
|
break
|
|
except Exception:
|
|
pass
|
|
finally:
|
|
if version_major and version_minor and patchlevel and extraversion is not None:
|
|
version = release = version_major + '.' + version_minor + '.' + patchlevel
|
|
if extraversion != '':
|
|
version = release = version + '-' + extraversion
|
|
else:
|
|
sys.stderr.write('Warning: Could not extract kernel version\n')
|
|
version = release = "unknown version"
|
|
|
|
# -- General configuration ------------------------------------------------
|
|
|
|
extensions = [
|
|
'breathe', 'sphinx.ext.todo',
|
|
'sphinx.ext.extlinks',
|
|
'sphinx.ext.autodoc',
|
|
'zephyr.application',
|
|
'zephyr.html_redirects',
|
|
'only.eager_only',
|
|
'zephyr.dtcompatible-role',
|
|
'zephyr.link-roles',
|
|
'sphinx_tabs.tabs'
|
|
]
|
|
|
|
# Only use SVG converter when it is really needed, e.g. LaTeX.
|
|
if tags.has("svgconvert"): # pylint: disable=undefined-variable
|
|
extensions.append('sphinxcontrib.rsvgconverter')
|
|
|
|
templates_path = ['_templates']
|
|
|
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
|
# for a list of supported languages.
|
|
#
|
|
# This is also used if you do content translation via gettext catalogs.
|
|
# Usually you set "language" from the command line for these cases.
|
|
language = None
|
|
|
|
exclude_patterns = ['_build']
|
|
if not west_found:
|
|
exclude_patterns.append('**/*west-apis*')
|
|
else:
|
|
exclude_patterns.append('**/*west-not-found*')
|
|
|
|
# This change will allow us to use bare back-tick notation to let
|
|
# Sphinx hunt for a reference, starting with normal "document"
|
|
# references such as :ref:, but also including :c: and :cpp: domains
|
|
# (potentially) helping with API (doxygen) references simply by using
|
|
# `name`
|
|
default_role = 'any'
|
|
|
|
pygments_style = 'sphinx'
|
|
|
|
# Additional lexer for Pygments (syntax highlighting)
|
|
lexers['DTS'] = DtsLexer()
|
|
|
|
todo_include_todos = False
|
|
|
|
rst_epilog = """
|
|
.. include:: /substitutions.txt
|
|
"""
|
|
|
|
# -- Options for HTML output ----------------------------------------------
|
|
|
|
html_theme = "sphinx_rtd_theme"
|
|
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
|
html_theme_options = {
|
|
'prev_next_buttons_location': None
|
|
}
|
|
html_title = "Zephyr Project Documentation"
|
|
html_logo = 'images/Zephyr-Kite-logo.png'
|
|
html_favicon = 'images/zp_favicon.png'
|
|
html_static_path = ['{}/doc/_static'.format(ZEPHYR_BASE)]
|
|
html_last_updated_fmt = '%b %d, %Y'
|
|
html_domain_indices = False
|
|
html_split_index = True
|
|
html_show_sourcelink = False
|
|
html_show_sphinx = False
|
|
html_search_scorer = '_static/js/scorer.js'
|
|
|
|
is_release = tags.has('release') # pylint: disable=undefined-variable
|
|
docs_title = 'Docs / {}'.format(version if is_release else 'Latest')
|
|
html_context = {
|
|
'show_license': True,
|
|
'docs_title': docs_title,
|
|
'is_release': is_release,
|
|
'theme_logo_only': False,
|
|
'current_version': version,
|
|
'versions': (("latest", "/"),
|
|
("2.5.0", "/2.5.0/"),
|
|
("2.4.0", "/2.4.0/"),
|
|
("2.3.0", "/2.3.0/"),
|
|
("2.2.0", "/2.2.0/"),
|
|
("1.14.1", "/1.14.1/"),
|
|
)
|
|
}
|
|
|
|
# -- Options for LaTeX output ---------------------------------------------
|
|
|
|
latex_elements = {
|
|
'preamble': r'\setcounter{tocdepth}{2}',
|
|
}
|
|
|
|
latex_documents = [
|
|
('index', 'zephyr.tex', 'Zephyr Project Documentation',
|
|
'many', 'manual'),
|
|
]
|
|
|
|
# -- Options for Breathe plugin -------------------------------------------
|
|
|
|
breathe_projects = {
|
|
"Zephyr": "{}/doxygen/xml".format(ZEPHYR_BUILD),
|
|
"doc-examples": "{}/doxygen/xml".format(ZEPHYR_BUILD)
|
|
}
|
|
breathe_default_project = "Zephyr"
|
|
breathe_domain_by_extension = {
|
|
"h": "c",
|
|
"c": "c",
|
|
}
|
|
breathe_separate_member_pages = True
|
|
breathe_show_enumvalue_initializer = True
|
|
|
|
cpp_id_attributes = [
|
|
'__syscall', '__deprecated', '__may_alias',
|
|
'__used', '__unused', '__weak',
|
|
'__DEPRECATED_MACRO', 'FUNC_NORETURN',
|
|
'__subsystem',
|
|
]
|
|
c_id_attributes = cpp_id_attributes
|
|
|
|
# -- Options for html_redirect plugin -------------------------------------
|
|
|
|
html_redirect_pages = redirects.REDIRECTS
|
|
|
|
# -- Linkcheck options ----------------------------------------------------
|
|
|
|
extlinks = {'jira': ('https://jira.zephyrproject.org/browse/%s', ''),
|
|
'github': ('https://github.com/zephyrproject-rtos/zephyr/issues/%s', '')
|
|
}
|
|
|
|
# some configuration for linkcheck builder
|
|
# noticed that we're getting false-positive link errors on JIRA, I suspect
|
|
# because it's taking too long for the server to respond so bump up the
|
|
# timeout (default=5) and turn off anchor checks (so only a HEAD request is
|
|
# done - much faster) Leave the ignore commented in case we want to remove
|
|
# jira link checks later...
|
|
|
|
linkcheck_timeout = 30
|
|
linkcheck_workers = 10
|
|
# linkcheck_ignore = [r'https://jira\.zephyrproject\.org/']
|
|
linkcheck_anchors = False
|
|
|
|
def setup(app):
|
|
app.add_css_file("css/zephyr-custom.css")
|
|
|
|
app.add_js_file("https://www.googletagmanager.com/gtag/js?id=UA-831873-47")
|
|
app.add_js_file("js/ga-tracker.js")
|
|
app.add_js_file("js/zephyr-custom.js")
|