doc: format configuration file
Format the configuration file so that it is more consistent (e.g. uniform usage of single/double quotes). Some minor cleanup performed too: removed some comments and a default setting. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This commit is contained in:
Gerard Marull-Paretas
Carles Cufí
parent
4b09faf4b9
commit
f4edff068f
1 changed files with 66 additions and 75 deletions
129
doc/conf.py
129
doc/conf.py
|
|
@ -20,17 +20,17 @@ if not ZEPHYR_BUILD:
|
|||
raise ValueError("ZEPHYR_BUILD environment variable undefined")
|
||||
ZEPHYR_BUILD = Path(ZEPHYR_BUILD)
|
||||
|
||||
# Add the 'extensions' directory to sys.path, to enable finding Sphinx
|
||||
# Add the '_extensions' directory to sys.path, to enable finding Sphinx
|
||||
# extensions within.
|
||||
sys.path.insert(0, str(ZEPHYR_BASE / 'doc' / '_extensions'))
|
||||
sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_extensions"))
|
||||
|
||||
# Add the '_scripts' directory to sys.path, to enable finding utility
|
||||
# modules.
|
||||
sys.path.insert(0, str(ZEPHYR_BASE / 'doc' / '_scripts'))
|
||||
sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_scripts"))
|
||||
|
||||
# Add the directory which contains the runners package as well,
|
||||
# for autodoc directives on runners.xyz.
|
||||
sys.path.insert(0, str(ZEPHYR_BASE / 'scripts' / 'west_commands'))
|
||||
sys.path.insert(0, str(ZEPHYR_BASE / "scripts" / "west_commands"))
|
||||
|
||||
from lexer.DtsLexer import DtsLexer
|
||||
import redirects
|
||||
|
|
@ -42,12 +42,12 @@ except ImportError:
|
|||
|
||||
# -- Project --------------------------------------------------------------
|
||||
|
||||
project = 'Zephyr Project'
|
||||
copyright = '2015-2021 Zephyr Project members and individual contributors'
|
||||
author = 'The Zephyr Project'
|
||||
project = "Zephyr Project"
|
||||
copyright = "2015-2021 Zephyr Project members and individual contributors"
|
||||
author = "The Zephyr Project"
|
||||
|
||||
# parse version from 'VERSION' file
|
||||
with open(ZEPHYR_BASE / 'VERSION') as f:
|
||||
with open(ZEPHYR_BASE / "VERSION") as f:
|
||||
m = re.match(
|
||||
(
|
||||
r"^VERSION_MAJOR\s*=\s*(\d+)$\n"
|
||||
|
|
@ -61,7 +61,7 @@ with open(ZEPHYR_BASE / 'VERSION') as f:
|
|||
)
|
||||
|
||||
if not m:
|
||||
sys.stderr.write('Warning: Could not extract kernel version\n')
|
||||
sys.stderr.write("Warning: Could not extract kernel version\n")
|
||||
version = "Unknown"
|
||||
else:
|
||||
major, minor, patch, extra = m.groups(1)
|
||||
|
|
@ -72,47 +72,41 @@ with open(ZEPHYR_BASE / 'VERSION') as f:
|
|||
# -- 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'
|
||||
"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')
|
||||
extensions.append("sphinxcontrib.rsvgconverter")
|
||||
|
||||
templates_path = ['_templates']
|
||||
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"]
|
||||
|
||||
exclude_patterns = ['_build']
|
||||
if not west_found:
|
||||
exclude_patterns.append('**/*west-apis*')
|
||||
exclude_patterns.append("**/*west-apis*")
|
||||
else:
|
||||
exclude_patterns.append('**/*west-not-found*')
|
||||
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'
|
||||
default_role = "any"
|
||||
|
||||
pygments_style = 'sphinx'
|
||||
pygments_style = "sphinx"
|
||||
|
||||
# Additional lexer for Pygments (syntax highlighting)
|
||||
lexers['DTS'] = DtsLexer()
|
||||
lexers["DTS"] = DtsLexer()
|
||||
|
||||
todo_include_todos = False
|
||||
|
||||
|
|
@ -124,53 +118,51 @@ rst_epilog = """
|
|||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
html_theme_options = {
|
||||
'prev_next_buttons_location': None
|
||||
}
|
||||
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 = [str(ZEPHYR_BASE / 'doc' / '_static')]
|
||||
html_last_updated_fmt = '%b %d, %Y'
|
||||
html_logo = "images/Zephyr-Kite-logo.png"
|
||||
html_favicon = "images/zp_favicon.png"
|
||||
html_static_path = [str(ZEPHYR_BASE / "doc" / "_static")]
|
||||
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'
|
||||
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')
|
||||
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", "/"),
|
||||
"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}',
|
||||
"preamble": r"\setcounter{tocdepth}{2}",
|
||||
}
|
||||
|
||||
latex_documents = [
|
||||
('index', 'zephyr.tex', 'Zephyr Project Documentation',
|
||||
'many', 'manual'),
|
||||
("index", "zephyr.tex", "Zephyr Project Documentation", "many", "manual"),
|
||||
]
|
||||
|
||||
# -- Options for Breathe plugin -------------------------------------------
|
||||
|
||||
breathe_projects = {
|
||||
"Zephyr": str(ZEPHYR_BUILD / "doxygen" / "xml"),
|
||||
"doc-examples": str(ZEPHYR_BUILD / "doxygen" / "xml")
|
||||
"doc-examples": str(ZEPHYR_BUILD / "doxygen" / "xml"),
|
||||
}
|
||||
breathe_default_project = "Zephyr"
|
||||
breathe_domain_by_extension = {
|
||||
|
|
@ -181,10 +173,15 @@ 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',
|
||||
"__syscall",
|
||||
"__deprecated",
|
||||
"__may_alias",
|
||||
"__used",
|
||||
"__unused",
|
||||
"__weak",
|
||||
"__DEPRECATED_MACRO",
|
||||
"FUNC_NORETURN",
|
||||
"__subsystem",
|
||||
]
|
||||
c_id_attributes = cpp_id_attributes
|
||||
|
||||
|
|
@ -194,25 +191,19 @@ html_redirect_pages = redirects.REDIRECTS
|
|||
|
||||
# -- Linkcheck options ----------------------------------------------------
|
||||
|
||||
extlinks = {'jira': ('https://jira.zephyrproject.org/browse/%s', ''),
|
||||
'github': ('https://github.com/zephyrproject-rtos/zephyr/issues/%s', '')
|
||||
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("js/zephyr-custom.js")
|
||||
|
||||
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")
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue