docs(misc fixes): fix misc items (details below)... (#8186)

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()

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'
+        branch = cfg_default_branch
-    elif branch == 'master':
+    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
+        debugging_breathe = 0
-        # formats are assembled by `conf.py`.  The -D option in the command
+        if debugging_breathe:
-        # line may go away if it does not, in fact, create some impact on
+            from sphinx.cmd.build import main as sphinx_build
-        # the doc-gen process.
+            # Don't allow parallel processing while debugging (the '-j' arg is removed).
-        cmd_line = f'sphinx-build -M html "{src}" "{dst}" -D version="{ver}" {env_opt} -j {cpu}'
+            sphinx_args = ['-M', 'html', f'{src}', f'{dst}', '-D', f'version={ver}']
-        cmd(cmd_line)
+
+            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))
 

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]
+            match = disabled_option_re.search(line)
-
+            if match:
-            for j, item in enumerate(line):
+                # Replace '0' with '1' without altering any other part of line.
-                if item == '0':
+                # Set `j` to index where '0' was found.
-                    line[j] = '1'
+                j = match.regs[1][0]
-
+                # Surgically insert '1' in place of '0'.
-            line = ' '.join(line)
+                lines[i] = line[:j] + '1' + line[j + 1:]
-            data[i] = line
         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()

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
+}
+

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
+# 22-Apr-2025 while the `-D version=...` on the command line works (as long as quotes
-# currently work as documented.  Sphinx documentation says of `-D setting=value`
+# are not placed around the version), having it added after `sphinx-build` has
-# "Override a configuration value set in the conf.py file.".
+# executed this script is not soon enough because we need the version in some
-# So we have to do this to get the version string into various values below.
+# 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"          ,

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
+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.
+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
+There is a way to load screens that gives you 2 additional (extended) options,
-:cpp:expr:`lv_screen_load_anim(scr, transition_type, time, delay, auto_del)`. The
+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

docs/src/details/integration/chip/renesas/index.rst

@@ -1,3 +1,5 @@
+.. _renesas:
+
 =======
 Renesas
 =======