Files
lvgl/docs/src/conf.py
T
2026-01-26 16:31:31 +01:00

580 lines
28 KiB
Python
Executable File

# #########################################################################
# Configuration file for the Sphinx documentation builder.
# Created by sphinx-quickstart on Wed Jun 12 16:38:40 2019.
#
# This file is execfile()'d with the current directory set to its
# containing directory.
#
# All configuration values have a default; some values are included
# below that are commented out and some of these serve to show the
# default. Note that not all possible configuration values are present.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# The major sections below each reflect a major section of that web page,
# and they are ordered in the same sequence so it is clear what config
# items go with what.
#
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath() to make it absolute, as shown here.
# #########################################################################
import os
import sys
from sphinx.builders.html import StandaloneHTMLBuilder
base_path = os.path.abspath(os.path.dirname(__file__))
# Add path to import link_roles.py and lv_example.py
sys.path.insert(0, os.path.abspath('./_ext'))
# Add path to import lvgl_version.py. Remember this is
# running under `sphinx-build` environment, not `build.py`.
sys.path.insert(0, base_path)
from lvgl_version import lvgl_version #NoQA
cfg_lv_version_file = 'lv_version.h'
# *************************************************************************
# Project Information
# *************************************************************************
project = 'LVGL'
copyright = '2021-%Y, LVGL Kft'
author = 'LVGL Community'
if __name__ == '__main__':
version_src_path = os.path.join(base_path, '../../lv_version.h')
else:
version_src_path = os.path.join(base_path, cfg_lv_version_file)
if os.path.isfile(version_src_path):
# We have lv_version.h. Use it.
version = lvgl_version(version_src_path)
else:
# We have to guess.
version = '9.3'
release = version
# Notes about `version` here:
# ---------------------------
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# A short X.Y version is extracted from `lv_version.h` using a cross-platform compatible
# Python function in lvgl_version.py, and passed in on `sphinx-build` command line.
#
# 22-Apr-2025 while the `-D version=...` on the command line works (as long as quotes
# are not placed around the version), having it added after `sphinx-build` has
# executed this script is not soon enough because we need the version in some
# strings below. So we need to get it here from `lv_version.h` in order to do that.
# *************************************************************************
# General Configuration
# *************************************************************************
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or custom extensions.
#
# As of 6-Jan-2025, `link_roles` is being commented out because it is being
# replaced by a manually-installed translation link in ./docs/index.rst.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.viewcode', # Eye icon at top of page to view page source code on GitHub.
'sphinx_copybutton', # Copy-to-clipboard button in code blocks & code examples.
'breathe',
'sphinx_sitemap',
'lv_example',
'sphinx_design',
# 'link_roles',
'sphinxcontrib.mermaid',
]
needs_extensions = {
'sphinxcontrib.mermaid': '0.9.2'
}
# If 'SPHINX_REREDIRECTS_STANDDOWN' environment variable exists and
# is set to a value not equal to '0', then do not add 'sphinx_reredirects'
# to extensions. This gives someone testing/editing/debugging documentation
# build the possibility of skipping adding redirects in the local environment
# if desired.
add_redirects = True
if 'SPHINX_REREDIRECTS_STANDDOWN' in os.environ:
if os.environ.get('SPHINX_REREDIRECTS_STANDDOWN') != '0':
print("sphinx_reredirects standing down as requested.")
add_redirects = False
if add_redirects:
extensions.append('sphinx_reredirects')
del add_redirects
# -------------------------------------------------------------------------
# Options for Highlighting
# -------------------------------------------------------------------------
# The default language to highlight source code in. The default is 'python'.
# The value should be a valid Pygments lexer name, see Showing code examples
# for more details.
highlight_language = 'c'
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'github-light'
pygments_dark_style = 'github-dark'
# -------------------------------------------------------------------------
# Options for Internationalisation
# -------------------------------------------------------------------------
# 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 = 'en'
# -------------------------------------------------------------------------
# Options for Markup
# -------------------------------------------------------------------------
default_role = 'literal'
# keep_warnings = False # True causes Sphinx warnings to be added to documents.
primary_domain = 'c' # Default: 'py'
# -------------------------------------------------------------------------
# Options for Source Files
# -------------------------------------------------------------------------
# List of glob-style patterns, relative to source directory, that
# match files and directories to ignore when looking for source files.
# These patterns also effect html_static_path and html_extra_path.
exclude_patterns = ['build', 'doxygen', 'intermediate', 'doxygen_html', 'Thumbs.db', '.DS_Store',
'README.md', 'README_*', 'lv_examples', 'env', '_ext', 'examples']
# The master toctree document. (Root of TOC tree.)
master_doc = 'index'
# The suffix(es) of source filenames.
# You can specify multiple suffixes as a dictionary per
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-source_suffix
source_suffix = {'.rst': 'restructuredtext'}
# -------------------------------------------------------------------------
# Options for Smart Quotes
# -------------------------------------------------------------------------
# Enabling smart quotes action to convert `--` to en dashes and `---` to em
# dashes. Converting quotation marks and ellipses is NOT done because the
# default `smartquotes_action` 'qDe' is changed to just 'D' below, which
# accomplishes the dash conversions as desired.
#
# For list of all possible smartquotes_action values, see:
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes_action
smartquotes = True
smartquotes_action = 'D'
smartquotes_excludes = {'builders': ['man', 'text', 'json', 'xml', 'latex']}
# -------------------------------------------------------------------------
# Options for Templating
# -------------------------------------------------------------------------
# A list of paths that contain extra templates (or templates that overwrite
# builtin/theme-specific templates). Relative paths are taken as relative
# to the configuration directory.
templates_path = ['_templates']
# -------------------------------------------------------------------------
# Options for Warning Control
# -------------------------------------------------------------------------
# suppress_warnings = ['app.add_directive', etc.]
# *************************************************************************
# Builder Options
# *************************************************************************
# -------------------------------------------------------------------------
# Options for HTML Builder
# -------------------------------------------------------------------------
# The theme for HTML output. See https://www.sphinx-doc.org/en/master/usage/theming.html
html_theme = 'furo'
# Theme options are theme-specific and customize the look and feel of a
# theme further. For a list of options available for each theme, see the
# theme documentation.
#
# Various other builders are derived from the HTML output, and also make use
# of these options.
html_theme_options = {
"sidebar_hide_name": True, # True when the logo carries project name
"light_logo": "images/logo-light.svg",
"dark_logo": "images/logo-dark.svg",
"top_of_page_buttons": ["view"],
# The below 3 direct the "top_of_page_buttons" to github for view and edit buttons.
"source_repository": "https://github.com/lvgl/lvgl/",
"source_branch": "master",
"source_directory": "docs/src/",
# "announcement": "<em>Semi-permanent announcement</em> from <code>conf.py</code>.",
}
html_sidebars = {
"**": [
"sidebar/brand.html",
"sidebar/version-selector.html",
"sidebar/search.html",
"sidebar/scroll-start.html",
"sidebar/navigation.html",
"sidebar/ethical-ads.html",
"sidebar/scroll-end.html",
"sidebar/variant-selector.html"
]
}
# For site map generation
if "LVGL_URLPATH" not in os.environ:
os.environ['LVGL_URLPATH'] = 'master'
_branch = os.getenv('LVGL_URLPATH')
html_baseurl = f"https://docs.lvgl.io/{_branch}/"
#lvgl_github_url = f"https://github.com/lvgl/lvgl/blob/{os.environ['LVGL_GITCOMMIT']}/docs"
#extlinks = {'github_link_base': (github_url + '%s', github_url)}
if "LVGL_GITCOMMIT" not in os.environ:
os.environ['LVGL_GITCOMMIT'] = 'master'
_git_commit_ref = os.getenv('LVGL_GITCOMMIT')
# These keys are used "bare" as template variables in:
# - sphinx_rtd_theme theme template: breadcrumbs.html
# - furo theme template: edit-this-page.html
# - furo theme template: view-this-page.html
html_context = {
'display_github': True,
'github_user': 'lvgl',
'github_repo': 'lvgl',
'github_version': _git_commit_ref,
'conf_py_path': '/docs/src/'
}
html_logo = ''
html_favicon = '_static/images/favicon.png'
html_css_files = [
'css/fontawesome.min.css',
'css/solid.min.css',
'css/brands.min.css',
'css/custom.css'
]
html_js_files = [
'js/custom.js',
'js/include_html.js'
]
html_static_path = ['_static']
html_last_updated_fmt = '' # Empty string uses default format: '%b %d, %Y'
html_last_updated_use_utc = False # False = use generating system's local date, not GMT.
html_permalinks = True # Default = True, add link anchor for each heading and description environment.
# 10-Mar-2025 16:21 -- commented out for Furo theme.
# html_sidebars = {
# '**': [
# 'relations.html', # needs 'show_related': True theme option to display
# 'searchbox.html',
# ]
# }
# html_domain_indices
# html_use_index = True # Default = True
# html_split_index
# html_copy_source = True # Default = True; if True, reStructuredText sources are included in HTML build as _sources/docname.
# html_show_sourcelink = True # Default = True
# html_sourcelink_suffix = '.txt' # Default = '.txt'
# html_use_opensearch = ''
# html_file_suffix = '.html' # Default = '.html'
# html_link_suffix = html_file_suffix
html_show_copyright = True # Default = True; shows copyright notice in footer.
# html_show_search_summary = True # Default = True
html_show_sphinx = False # Default = True; adds "Created using Sphinx" to footer.
# html_output_encoding = 'utf-8' # Default = 'utf-8'
# html_compact_lists = True # Default = True
# html_secnumber_suffix = '. ' # Default = '. '; set to ' ' to suppress final dot on section numbers.
# html_search_language = language # Default = language; language to be used for generating the HTML full-text search index.
# html_search_options
# Link images that have been resized with a scale option (scale, width, or height)
# to their original full-resolution image. This will not overwrite any link given
# by the target option on the image directive, if present.
#
# Tip
#
# To disable this feature on a per-image basis, add the no-scaled-link class to the image directive:
#
# .. image:: sphinx.png
# :scale: 50%
# :class: no-scaled-link
# html_scaled_image_link
# html_math_renderer = 'mathjax' # Default = 'mathjax'
# Change image search sequence: image files are searched in the order in which they appear here.
# See https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.html.StandaloneHTMLBuilder.supported_image_types
StandaloneHTMLBuilder.supported_image_types = [
'image/svg+xml',
'image/gif', #prefer gif over png
'image/png',
'image/jpeg'
]
# -------------------------------------------------------------------------
# Options for HTMLHelp Builder
# -------------------------------------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'LVGLdoc'
# -------------------------------------------------------------------------
# Options for LaTeX Builder
# -------------------------------------------------------------------------
latex_engine = 'xelatex'
latex_use_xindy = False
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
'inputenc': '',
'utf8extra': '',
'classoptions': ',openany,oneside',
'babel': '\\usepackage{babel}',
'passoptionstopackages': r'''
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}% depth of pdf bookmarks
''',
'preamble': r'''
\usepackage{fontspec}
\setmonofont{DejaVu Sans Mono}
\usepackage{silence}
\WarningsOff*
''',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'LVGL.tex', 'LVGL v' + version,
author, 'manual'),
]
# -------------------------------------------------------------------------
# Options for Manual Page Builder
# -------------------------------------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'lvgl', 'LVGL v' + version,
[author], 3)
]
# -------------------------------------------------------------------------
# Options for Texinfo Builder
# -------------------------------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'LVGL', 'LVGL v' + version,
author, 'Contributors of LVGL', 'One line description of project.',
'Miscellaneous'),
]
# *************************************************************************
# Domain Options
# *************************************************************************
# -------------------------------------------------------------------------
# Options for the C Domain
# -------------------------------------------------------------------------
# -------------------------------------------------------------------------
# Options for the CPP Domain
# -------------------------------------------------------------------------
# *************************************************************************
# Configuration for Sphinx Extensions
# *************************************************************************
# -------------------------------------------------------------------------
# Options for sphinx_rtd_dark_mode extension
# -------------------------------------------------------------------------
default_dark_mode = False
# -------------------------------------------------------------------------
# Options for lv_example extension
# -------------------------------------------------------------------------
repo_commit_hash = _git_commit_ref
# -------------------------------------------------------------------------
# Options for sphinx.ext.todo extension
# -------------------------------------------------------------------------
# If true, `todo` and `todoList` directives produce output, else they produce nothing.
# See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
todo_include_todos = True
# -------------------------------------------------------------------------
# Options for sphinx_sitemap extension
# -------------------------------------------------------------------------
# See https://sphinx-sitemap.readthedocs.io/en/latest/index.html
sitemap_url_scheme = "{link}"
# Prettyfy output using 4 spaces to indent.
sitemap_indent = 4
# -------------------------------------------------------------------------
# Options for breathe extension
# -------------------------------------------------------------------------
# See https://breathe.readthedocs.io/en/latest/
breathe_projects = {
"lvgl": "xml/",
}
breathe_default_project = "lvgl"
# breathe_debug_trace_directives = True
# -------------------------------------------------------------------------
# Options for sphinx_reredirects
# -------------------------------------------------------------------------
# The below generates .HTML page redirects for pages that have been moved.
# Browsers are redirected via `<meta http-equiv="refresh" content="0; url=new_url">`.
redirects = {
"CONTRIBUTING": "contributing/index.html" ,
"get-started/index": "../getting_started.html" ,
"get-started/os/nuttx": "../../integration/rtos/nuttx.html" ,
"get-started/platforms/arduino": "../../integration/framework/arduino.html" ,
"get-started/platforms/espressif": "../../integration/chip/espressif.html" ,
"get-started/platforms/pc-simulator": "../../integration/ide/pc-simulator.html" ,
"get-started/quick-overview": "../getting_started.html" ,
"integration/framework/arduino": "../../integration/frameworks/arduino.html" ,
"integration/framework/index": "../../integration/frameworks/index.html" ,
"integration/framework/platformio": "../../integration/frameworks/platformio.html" ,
"integration/framework/tasmota-berry": "../../integration/frameworks/tasmota-berry.html" ,
"integration/ide/pc-simulator": "../../integration/ide/pc-simulator.html" ,
"integration/os/rt-thread": "../../integration/os/rt-thread.html" ,
"intro/getting_started/index": "../../getting_started/index.html" ,
"layouts/flex": "../common-widget-features/layouts/flex.html" ,
"layouts/grid": "../common-widget-features/layouts/grid.html" ,
"layouts/index": "../common-widget-features/layouts/index.html" ,
"others/file_explorer": "../auxiliary-modules/file_explorer.html" ,
"others/font_manager": "../auxiliary-modules/font_manager.html" ,
"others/fragment": "../auxiliary-modules/fragment.html" ,
"others/gridnav": "../auxiliary-modules/gridnav.html" ,
"others/ime_pinyin": "../auxiliary-modules/ime_pinyin.html" ,
"others/imgfont": "../auxiliary-modules/imgfont.html" ,
"others/index": "../auxiliary-modules/index.html" ,
"others/monkey": "../auxiliary-modules/monkey.html" ,
"others/obj_id": "../auxiliary-modules/obj_id.html" ,
"others/obj_property": "../auxiliary-modules/obj_property.html" ,
"others/observer": "../main-modules/observer.html" ,
"others/snapshot": "../auxiliary-modules/snapshot.html" ,
"overview/animations": "../main-modules/animation.html" ,
"overview/color": "../main-modules/color.html" ,
"overview/coord": "../common-widget-features/coord.html" ,
"overview/debugging/gdb_plugin": "../../debugging/gdb_plugin.html" ,
"overview/debugging/index": "../../debugging/index.html" ,
"overview/debugging/log": "../../debugging/log.html" ,
"overview/debugging/profiler": "../../debugging/profiler.html" ,
"overview/debugging/vg_lite_tvg": "../../debugging/vg_lite_tvg.html" ,
"overview/display": "../main-modules/display/index.html" ,
"overview/event": "../common-widget-features/event.html" ,
"overview/font": "../main-modules/font.html" ,
"overview/fs": "../main-modules/fs.html" ,
"overview/image": "../main-modules/image.html" ,
"overview/indev": "../main-modules/indev.html" ,
"overview/index": "../main-modules/index.html" ,
"overview/layer": "../common-widget-features/layer.html" ,
"overview/new_widget": "../widgets/new_widget.html" ,
"overview/obj": "../common-widget-features/obj.html" ,
"overview/renderers/arm2d": "../../integration/renderers/arm2d.html" ,
"overview/renderers/index": "../../integration/renderers/index.html" ,
"overview/renderers/nema_gfx": "../../integration/renderers/nema_gfx.html" ,
"overview/renderers/pxp": "../../integration/renderers/nxp_pxp.html" ,
"overview/renderers/sdl": "../../integration/renderers/sdl.html" ,
"overview/renderers/stm32_dma2d": "../../integration/renderers/stm32_dma2d.html" ,
"overview/renderers/sw": "../../integration/renderers/sw.html" ,
"overview/renderers/vg_lite": "../../integration/renderers/vg_lite.html" ,
"overview/renderers/vglite": "../../integration/renderers/nxp_vglite_gpu.html" ,
"overview/scroll": "../common-widget-features/scroll.html" ,
"overview/style": "../common-widget-features/styles/styles.html" ,
"overview/style-props": "../common-widget-features/styles/style-properties.html" ,
"overview/timer": "../main-modules/timer.html" ,
"porting/display": "../main-modules/display/index.html" ,
"porting/draw": "../main-modules/draw.html" ,
"porting/indev": "../main-modules/indev.html" ,
"porting/index": "../integration/adding-lvgl-to-your-project/index.html" ,
"porting/os": "../integration/adding-lvgl-to-your-project/threading.html",
"porting/project": "../integration/adding-lvgl-to-your-project/connecting_lvgl.html",
"porting/sleep": "../integration/adding-lvgl-to-your-project/threading.html",
"porting/tick": "../integration/adding-lvgl-to-your-project/connecting_lvgl.html",
"porting/timer_handler": "../integration/adding-lvgl-to-your-project/timer_handler.html",
"widgets/obj": "../widgets/base_widget.html" ,
# After 27-Nov-2025
"intro/getting_started/index": "../../getting_started/index.html" ,
"details/auxiliary-modules/observer/index": "../../../main-modules/observer/index.html" ,
"details/common-widget-features/layouts/flex": "../../../common-widget-features/layouts/flex.html" ,
"details/common-widget-features/layouts/grid": "../../../common-widget-features/layouts/grid.html" ,
"details/common-widget-features/layouts/index": "../../../common-widget-features/layouts/index.html" ,
"details/common-widget-features/styles/index": "../../../common-widget-features/styles/index.html" ,
"details/integration/framework/arduino": "../../../integration/frameworks/arduino.html" ,
"details/integration/os/nuttx": "../../../integration/rtos/nuttx.html" ,
"details/integration/os/rt-thread": "../../../integration/rtos/rt-thread.html" ,
"details/integration/os/zephyr": "../../../integration/rtos/zephyr.html" ,
"details/libs/gltf": "../../libs/gltf.html" ,
"details/main-modules/display/overview": "../../../main-modules/display/overview.html" ,
"details/main-modules/indev": "../../main-modules/indev/index.html" ,
"details/widgets/index": "../../widgets/index.html" ,
"details/xml/editor/index": "../../../xml/editor/index.html" ,
"details/xml/index": "../../xml/index.html" ,
"details/xml/integration/renesas-dev-tools": "../../../xml/integration/renesas-dev-tools.html" ,
"details/xml/tools/cli": "../../../xml/tools/cli.html" ,
"details/xml/tools/figma": "../../../xml/tools/figma.html" ,
"details/xml/tools/online_share": "../../../xml/tools/online_share.html" ,
"details/xml/xml/index": "../../../xml/xml/index.html" ,
"details/xml/features/index": "../../../xml/features/index.html" ,
}
# Example configuration for intersphinx: refer to the Python standard library.
def setup(app):
pass
# app.add_config_value('recommonmark_config', {
# 'enable_eval_rst': True,
# 'enable_auto_toc_tree': 'True',
# }, True)
# app.add_transform(AutoStructify)
# app.add_css_file('css/custom.css')
# app.add_css_file('css/fontawesome.min.css')