From 209838a23092c3461ffb1ff40876f9a54e91b386 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 7 May 2025 04:38:26 -0600 Subject: [PATCH] docs(misc fixes): fix misc items (details below)... (#8186) --- docs/announce.py | 32 +++++++++- docs/build.py | 37 ++++++++---- docs/config_builder.py | 32 ++++++---- docs/src/_static/css/custom.css | 20 ++++++- docs/src/conf.py | 60 +++++++++++++++---- .../details/common-widget-features/basics.rst | 25 ++++---- .../integration/chip/renesas/index.rst | 2 + 7 files changed, 160 insertions(+), 48 deletions(-) diff --git a/docs/announce.py b/docs/announce.py index 75cfc430cf..1efbe2edf2 100644 --- a/docs/announce.py +++ b/docs/announce.py @@ -25,9 +25,28 @@ It is the designer's intention that: import os import datetime -__all__ = ('announce', 'announce_start', 'announce_finish', 'announce_set_silent_mode') +__all__ = ('announce', 'announce_colored', 'announce_start', 'announce_finish', 'announce_set_silent_mode') _announce_start_time: datetime.datetime _announce_silent_mode: bool = False +_console_color_commands = { + 'default' : '\x1b[0m', + 'black' : '\x1b[30m', + 'red' : '\x1b[31m', + 'green' : '\x1b[32m', + 'yellow' : '\x1b[33m', + 'blue' : '\x1b[34m', + 'majenta' : '\x1b[35m', + 'cyan' : '\x1b[36m', + 'white' : '\x1b[37m', + 'bright_black' : '\x1b[90m', + 'bright_red' : '\x1b[91m', + 'bright_green' : '\x1b[92m', + 'bright_yellow' : '\x1b[93m', + 'bright_blue' : '\x1b[94m', + 'bright_majenta': '\x1b[95m', + 'bright_cyan' : '\x1b[96m', + 'bright_white' : '\x1b[97m' +} def _announce(file: str, args: tuple, start: bool, box: bool, box_char: str): @@ -65,6 +84,17 @@ def announce(file: str, *args, box: bool = False, box_char: str = '*'): _announce(file, args, False, box, box_char) +def announce_colored(file: str, clr: str, *args, box: bool = False, box_char: str = '*'): + global _announce_start_time + _announce_start_time = None + if len(args) > 0 and clr in _console_color_commands: + # Tuples are non-mutable so we have to build a new one -- can't insert new elements. + new_args_tuple = (_console_color_commands[clr],) + args + (_console_color_commands['default'],) + _announce(file, new_args_tuple, False, box, box_char) + else: + _announce(file, args, False, box, box_char) + + def announce_start(file: str, *args, box: bool = False, box_char: str = '*'): global _announce_start_time _announce_start_time = datetime.datetime.now() diff --git a/docs/build.py b/docs/build.py index a608f57e06..06eb9f2980 100755 --- a/docs/build.py +++ b/docs/build.py @@ -197,6 +197,7 @@ cfg_lv_conf_filename = 'lv_conf.h' cfg_lv_version_filename = 'lv_version.h' cfg_doxyfile_filename = 'Doxyfile' cfg_top_index_filename = 'index.rst' +cfg_default_branch = 'master' # Filename generated in `latex_output_dir` and copied to `pdf_output_dir`. cfg_pdf_filename = 'LVGL.pdf' @@ -353,7 +354,7 @@ def run(args): print(f'Argument [{arg}] not recognized.') print() print_usage_note() - exit(1) + exit(2) # 2 = customary Unix command-line syntax error. # '-E' option forces Sphinx to rebuild its environment so all docs are # fully regenerated, even if not changed. @@ -507,8 +508,8 @@ def run(args): # If above failed (i.e. `branch` not valid), default to 'master'. if status != 0: - branch = 'master' - elif branch == 'master': + branch = cfg_default_branch + elif branch == cfg_default_branch: # Expected in most cases. Nothing to change. pass else: @@ -517,7 +518,7 @@ def run(args): branch = branch[8:] else: # Default to 'master'. - branch = 'master' + branch = cfg_default_branch os.environ['LVGL_URLPATH'] = branch os.environ['LVGL_GITCOMMIT'] = branch @@ -717,13 +718,27 @@ def run(args): src = intermediate_dir dst = output_dir cpu = os.cpu_count() - # As of 22-Feb-2025, sadly the -D version=xxx is not working as documented. - # So the version strings applicable to Latex/PDF/man pages/texinfo - # formats are assembled by `conf.py`. The -D option in the command - # line may go away if it does not, in fact, create some impact on - # the doc-gen process. - cmd_line = f'sphinx-build -M html "{src}" "{dst}" -D version="{ver}" {env_opt} -j {cpu}' - cmd(cmd_line) + + debugging_breathe = 0 + if debugging_breathe: + from sphinx.cmd.build import main as sphinx_build + # Don't allow parallel processing while debugging (the '-j' arg is removed). + sphinx_args = ['-M', 'html', f'{src}', f'{dst}', '-D', f'version={ver}'] + + if len(env_opt) > 0: + sphinx_args.append(f'{env_opt}') + + sphinx_build(sphinx_args) + else: + # The -D option correctly replaces (overrides) configuration attribute + # values in the `conf.py` module. Since `conf.py` now correctly + # computes its own `version` value, we don't have to override it here + # with a -D options. If it should need to be used in the future, + # the value after the '=' MUST NOT have quotation marks around it + # or it won't work. Correct usage: f'-D version={ver}' . + cmd_line = f'sphinx-build -M html "{src}" "{dst}" -j {cpu} {env_opt}' + cmd(cmd_line) + t2 = datetime.now() announce(__file__, 'HTML gen time : ' + str(t2 - t1)) diff --git a/docs/config_builder.py b/docs/config_builder.py index cbe32dced5..7ed6d71fad 100644 --- a/docs/config_builder.py +++ b/docs/config_builder.py @@ -8,6 +8,8 @@ from ../lv_conf_template.h that has: 3. its #if 0 directive set to #if 1. """ import os +import sys +import re base_path = os.path.dirname(__file__) dst_config = os.path.join(base_path, 'lv_conf.h') @@ -16,10 +18,12 @@ src_config = os.path.abspath(os.path.join( '..', 'lv_conf_template.h' )) +disabled_option_re = re.compile(r'^\s*#define\s+\w+\s+(\b0\b)') def run(c_path=None): global dst_config + os.chdir(base_path) if c_path is not None: dst_config = c_path @@ -27,9 +31,9 @@ def run(c_path=None): with open(src_config, 'r') as f: data = f.read() - data = data.split('\n') + lines = data.split('\n') - for i, line in enumerate(data): + for i, line in enumerate(lines): if 'LV_USE_PROFILER' in line: continue @@ -43,19 +47,18 @@ def run(c_path=None): continue if 'LV_USE' in line or ('LV_FONT' in line and '#define' in line): - line = [item for item in line.split(' ') if item] - - for j, item in enumerate(line): - if item == '0': - line[j] = '1' - - line = ' '.join(line) - data[i] = line + match = disabled_option_re.search(line) + if match: + # Replace '0' with '1' without altering any other part of line. + # Set `j` to index where '0' was found. + j = match.regs[1][0] + # Surgically insert '1' in place of '0'. + lines[i] = line[:j] + '1' + line[j + 1:] elif line.startswith('#if 0'): line = line.replace('#if 0', '#if 1') - data[i] = line + lines[i] = line - data = '\n'.join(data) + data = '\n'.join(lines) with open(dst_config, 'w') as f: f.write(data) @@ -64,3 +67,8 @@ def run(c_path=None): def cleanup(): if os.path.exists(dst_config): os.remove(dst_config) + + +if __name__ == '__main__': + """Make module importable as well as run-able.""" + run() diff --git a/docs/src/_static/css/custom.css b/docs/src/_static/css/custom.css index d9a8341f8f..8bb3e5134c 100644 --- a/docs/src/_static/css/custom.css +++ b/docs/src/_static/css/custom.css @@ -254,18 +254,34 @@ div.body { * .highlight .nf -- function names * .highlight .nl -- code labels * .descname .n -- API documentation function names + * .highlight .p -- Punctuation + * .highlight -- Plain text in a `.. code-block:: none` block * The first 2 were created by lightening the `pygments.css` colors without changing their - * angle on the color wheel. The added "conditional" also limits this change to + * angle on the color wheel. The added attribute "conditional" also limits this change to * DARK MODE only instead of both light and dark modes. */ +/* Name.Function */ html[data-theme="dark"] .highlight .nf { - color: #3569f5; + color: #ccd285; } +/* Name.Label */ html[data-theme="dark"] .highlight .nl { color: #0043e2; } +/* Name */ html[data-theme="dark"] .descname .n { color: #0a44de; } + +/* Punctuation */ +html[data-theme="dark"] .highlight .p { + color: #5c7c72 +} + +/* Plain text. */ +html[data-theme="dark"] .highlight { + background: #ffffff; color: #bfbfbf +} + diff --git a/docs/src/conf.py b/docs/src/conf.py index f140b83c21..51ba1f2505 100755 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -10,6 +10,9 @@ # # 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 @@ -30,7 +33,6 @@ from lvgl_version import lvgl_version #NoQA # ************************************************************************* # Project Information -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information # ************************************************************************* project = 'LVGL' @@ -51,16 +53,15 @@ release = version # 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-Feb-2025 Sadly, the `-D version=...` on the command line was found to not -# currently work as documented. Sphinx documentation says of `-D setting=value` -# "Override a configuration value set in the conf.py file.". -# So we have to do this to get the version string into various values below. +# 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 -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration # ************************************************************************* # If your documentation needs a minimal Sphinx version, state it here. @@ -84,13 +85,28 @@ extensions = [ 'sphinx_rtd_dark_mode', # 'link_roles', 'sphinxcontrib.mermaid', - 'sphinx_reredirects' ] 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 # ------------------------------------------------------------------------- @@ -117,6 +133,7 @@ language = 'en' # ------------------------------------------------------------------------- default_role = 'literal' # keep_warnings = False # True causes Sphinx warnings to be added to documents. +primary_domain = 'c' # Default: 'py' # ------------------------------------------------------------------------- # Options for Source Files @@ -166,12 +183,10 @@ templates_path = ['_templates'] # ************************************************************************* # Builder Options -# https://www.sphinx-doc.org/en/master/usage/configuration.html#builder-options # ************************************************************************* # ------------------------------------------------------------------------- # Options for HTML Builder -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output # ------------------------------------------------------------------------- # The theme for HTML output. See https://www.sphinx-doc.org/en/master/usage/theming.html html_theme = 'sphinx_rtd_theme' @@ -216,11 +231,15 @@ if "LVGL_GITCOMMIT" not in os.environ: _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 = { - 'github_version': _git_commit_ref, + 'display_github': True, 'github_user': 'lvgl', 'github_repo': 'lvgl', - 'display_github': True, + 'github_version': _git_commit_ref, 'conf_py_path': '/docs/src/' } @@ -366,6 +385,20 @@ texinfo_documents = [ +# ************************************************************************* +# Domain Options +# ************************************************************************* + +# ------------------------------------------------------------------------- +# Options for the C Domain +# ------------------------------------------------------------------------- + +# ------------------------------------------------------------------------- +# Options for the CPP Domain +# ------------------------------------------------------------------------- + + + # ************************************************************************* # Configuration for Sphinx Extensions # ************************************************************************* @@ -401,6 +434,9 @@ breathe_projects = { "lvgl": "xml/", } +breathe_default_project = "lvgl" +# breathe_debug_trace_directives = True + # ------------------------------------------------------------------------- # Options for sphinx_reredirects # ------------------------------------------------------------------------- @@ -427,7 +463,7 @@ redirects = { "integration/chip/espressif": "../../details/integration/chip/espressif.html" , "integration/chip/index": "../../details/integration/chip/index.html" , "integration/chip/nxp": "../../details/integration/chip/nxp.html" , - "integration/chip/renesas": "../../details/integration/chip/renesas.html" , + "integration/chip/renesas": "../../details/integration/chip/renesas/index.html" , "integration/chip/stm32": "../../details/integration/chip/stm32.html" , "integration/driver/X11": "../../details/integration/driver/X11.html" , "integration/driver/display/fbdev": "../../../details/integration/driver/display/fbdev.html" , diff --git a/docs/src/details/common-widget-features/basics.rst b/docs/src/details/common-widget-features/basics.rst index fc0e6a3028..c00e00db7e 100644 --- a/docs/src/details/common-widget-features/basics.rst +++ b/docs/src/details/common-widget-features/basics.rst @@ -143,7 +143,7 @@ it. Therefore, all positions are relative to the parent. .. code-block:: c - lv_obj_t * parent = lv_obj_create(lv_screen_active()); /* Create a parent Widget on current screen */ + lv_obj_t * parent = lv_obj_create(lv_screen_active()); /* Create a parent Widget on current Screen */ lv_obj_set_size(parent, 100, 80); /* Set size of parent */ lv_obj_t * widget1 = lv_obj_create(parent); /* Create a Widget on previously created parent Widget */ @@ -187,14 +187,14 @@ drawn within. lv_event_set_ext_draw_size(e, 30); /*Set 30px extra draw area around the widget*/ } -Create and delete Widgets -------------------------- +Creating and deleting Widgets +----------------------------- In LVGL, Widgets can be created and deleted dynamically at run time. It means only the currently created (existing) Widgets consume RAM. -This allows for the creation of a screen just when a button is clicked -to open it, and for deletion of screens when a new screen is loaded. +This allows for the creation of a Screen just when a button is clicked +to open it, and for deletion of Screens when a new Screen is loaded. UIs can be created based on the current environment of the device. For example one can create meters, charts, bars and sliders based on the @@ -334,11 +334,16 @@ Loading Screens To load a new screen, use :cpp:expr:`lv_screen_load(scr1)`. This sets ``scr1`` as the Active Screen. -Load Screen with Animation -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Load Screen with Extended Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A new screen can be loaded with animation by using -:cpp:expr:`lv_screen_load_anim(scr, transition_type, time, delay, auto_del)`. The +There is a way to load screens that gives you 2 additional (extended) options, +allowing the caller to specify: + +- an optional transition method, and +- an option to gracefully delete the screen that was being displayed. + +:cpp:expr:`lv_screen_load_anim(scr, transition_type, time, delay, auto_del)`. The following transition types exist: - :cpp:enumerator:`LV_SCR_LOAD_ANIM_NONE`: Switch immediately after ``delay`` milliseconds @@ -348,7 +353,7 @@ following transition types exist: - :cpp:enumerator:`LV_SCR_LOAD_ANIM_FADE_IN` and :cpp:enumerator:`LV_SCR_LOAD_ANIM_FADE_OUT`: Fade the new screen over the old screen, or vice versa Setting ``auto_del`` to ``true`` will automatically delete the old -screen when the animation is finished. +screen when the animation (if any) is finished. The new screen will become active (returned by :cpp:func:`lv_screen_active`) when the animation starts after ``delay`` time. All inputs are disabled diff --git a/docs/src/details/integration/chip/renesas/index.rst b/docs/src/details/integration/chip/renesas/index.rst index a6d06c9809..b930b326f6 100644 --- a/docs/src/details/integration/chip/renesas/index.rst +++ b/docs/src/details/integration/chip/renesas/index.rst @@ -1,3 +1,5 @@ +.. _renesas: + ======= Renesas =======