docs: miscellaneous improvements (#8552)

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-BUILDDIR      = build
 SOURCEDIR     = intermediate
+BUILDDIR      = build
 
 # SOURCEDIR can be overridden by LVGL_DOC_BUILD_INTERMEDIATE_DIR
 LEN           := $(shell printf '%s' '$(LVGL_DOC_BUILD_INTERMEDIATE_DIR)' | wc -c)

docs/build.py

@@ -672,9 +672,13 @@ 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
+        # The -D option correctly replaces (overrides) configuration attribute
-        # formats are assembled by `conf.py`.
+        # 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 latex "{src}" "{dst}" -j {cpu} --fail-on-warning --keep-going'
         cmd(cmd_line)
 

docs/make.bat

@@ -24,11 +24,13 @@ setlocal ENABLEDELAYEDEXPANSION
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
+
 if "%LVGL_DOC_BUILD_INTERMEDIATE_DIR%" == "" (
 	set SOURCEDIR=intermediate
 ) else (
 	set SOURCEDIR=%LVGL_DOC_BUILD_INTERMEDIATE_DIR%
 )
+
 if "%LVGL_DOC_BUILD_OUTPUT_DIR%" == "" (
 	set BUILDDIR=build
 ) else (

docs/src/_static/css/custom.css

@@ -1103,7 +1103,15 @@ dl.field-list > dd {
 div .lvgl-figure-caption p {
   font-size: 0.8rem;
   text-align: center;
-  margin-bottom: 32px;
+  margin-bottom: 2rem;
+}
+
+figure figcaption .caption-text {
+  font-size: 0.8rem;
+}
+
+article figure {
+  margin-bottom: 2rem;
 }
 
 /*-------------------------------------------------------------------------

docs/src/details/auxiliary-modules/obj_property.rst

@@ -24,7 +24,7 @@ properties of Widgets.  It's intended use is to:
     - any external input source (e.g. serial)
 
 While using it consumes more program space and more CPU overhead while setting and
-getting Widget properties, it is designed so minimize that additional CPU overhead.
+getting Widget properties, it is designed so as to minimize that additional CPU overhead.
 
 
 

docs/src/details/integration/adding-lvgl-to-your-project/threading.rst

@@ -82,7 +82,7 @@ LVGL manages many complex data structures, and those structures are "system
 resources" that must be protected from being "seen" by other threads in an
 inconsistent state.  A high percentage LVGL functions (functions that start with
 ``lv_``) either read from or change those data structures.  Those that change them
-place the data in an inconsistent state during execution (because such changes are
+place the data in an inconsistent state during call execution (because such changes are
 multi-step sequences), but return them to a consistent state before those functions
 return.  For this reason, execution of each LVGL function must be allowed to complete
 before any other LVGL function is started.
@@ -177,7 +177,7 @@ Method 2:  Use a MUTEX
 ----------------------
 A MUTEX stands for "MUTually EXclusive" and is a synchronization primitive that
 protects the state of a system resource from being modified or accessed by multiple
-threads of execution at once.  In other words, it makes data so protected "appear"
+threads of execution at the same time.  In other words, it makes data thus protected "appear"
 atomic (all threads using this data "see" it in a consistent state).  Most OSes
 provide MUTEXes.
 
@@ -190,9 +190,12 @@ assigned, that MUTEX performs such protection by programmers:
 2.  releasing the MUTEX (a.k.a. unlocking it) after that access or modification
     is complete.
 
+Good design practices for using a MUTEX stress that the time period that the MUTEX is
+locked is kept as short as possible.
+
 If a thread attempts to acquire (lock) the MUTEX while another thread "owns" it,
 that thread waits on the other thread to release (unlock) it before it is allowed
-to continue execution.
+to continue to execute.
 
 To be clear:  this must be done *both* by threads that READ from that resource, and
 threads that MODIFY that resource.

docs/src/details/main-modules/display/overview.rst

@@ -52,7 +52,7 @@ it is representing, as well as other things relevant to its lifetime:
 - The :ref:`draw_buffers` assigned to it
 - The :ref:`flush_callback` function that moves pixels from :ref:`draw_buffers` to Display hardware
 - What areas of the display have been updated (made "dirty") so rendering logic can
-  compute what to render during a :ref:`display refresh <basic_data_flow>`
+  compute what to render during a display refresh
 - Optional custom pointer as :ref:`display_user_data`
 
 

docs/src/intro/getting_started/learn_the_basics.rst

@@ -27,16 +27,24 @@ writing such a callback in an effective way.
 This chapter will show the basics to give an idea about how LVGL works and how it can be used.
 For more details about each feature visit that feature's dedicated documentation page.
 
-.. _basic_data_flow:
 
-Basic Data Flow
+.. _lvgl_integration_overview:
----------------
 
-1. **Driver Initialization**: It's the user's responsibility to set up the clock, timers, peripherals, etc.
+LVGL Integration Overview
-2. **Call lv_init()**: It initializes LVGL itself
+-------------------------
-3. **Create display and input devices**: Create display(s) (:cpp:type:`lv_display_t`) and input device(s)  (:cpp:type:`lv_indev_t`) and set up their callbacks
+
-4. **Create the UI**: Call LVGL functions to create screens, widgets, styles, animations, events, etc.
+The following is an overview of how to integrate LVGL into your project.  Complete
-5. **Call lv_timer_handler() in a loop**: It handles all the LVGL-related tasks:
+details are available at :ref:`adding_lvgl_to_your_project`.
+
+:Driver Initialization:              It is the user's responsibility to set up the
+                                     clock, timers, peripherals, etc.
+:Call lv_init():                     Initialize LVGL itself.
+:Create display and input devices:   Create display(s) (:cpp:type:`lv_display_t`)
+                                     and input device(s)  (:cpp:type:`lv_indev_t`)
+                                     and set up their callbacks.
+:Create the UI:                      Call LVGL functions to create screens, widgets,
+                                     styles, animations, events, etc.
+:Call lv_timer_handler() in a loop:  This handles all the LVGL-related tasks:
 
    - refresh display(s),
    - read input devices,
@@ -44,11 +52,11 @@ Basic Data Flow
    - run any animations, and
    - run user-created timers.
 
-Integration example
--------------------
 
-This is just a brief example of how to add LVGL to a new project. For more details
+Example
-check out :ref:`adding_lvgl_to_your_project`.
+~~~~~~~
+
+This is a brief example showing how simple it is to add LVGL to a new project.
 
 .. code-block:: c
 
@@ -62,44 +70,46 @@ check out :ref:`adding_lvgl_to_your_project`.
 
         lv_display_t * display = lv_display_create(320, 240);
 
-        /*LVGL will render to this 1/10 screen sized buffer for 2 bytes/pixel*/
+        /* LVGL will render to this 1/10 screen sized buffer for 2 bytes/pixel */
         static uint8_t buf[320 * 240 / 10 * 2];
         lv_display_set_buffers(display, buf, NULL, LV_DISPLAY_RENDER_MODE_PARTIAL);
 
-        /*This callback will display the rendered image*/
+        /* This callback will display the rendered image */
         lv_display_set_flush_cb(display, my_flush_cb);
 
-        /*Create widgets*/
+        /* Create widgets */
         lv_obj_t * label = lv_label_create(lv_screen_active());
         lv_label_set_text(label, "Hello LVGL!");
 
-        /*Make LVGL periodically execute its tasks*/
+        /* Make LVGL periodically execute its tasks */
         while(1) {
+            /* Provide updates to currently-displayed Widgets here. */
             lv_timer_handler();
             my_sleep(5);  /*Wait 5 milliseconds before processing LVGL timer again*/
         }
     }
 
-    /*Return the elapsed milliseconds since startup.
+    /* Return the elapsed milliseconds since startup.
-     *It needs to be implemented by the user*/
+     * It needs to be implemented by the user */
     uint32_t my_get_millis(void)
     {
         return my_tick_ms;
     }
 
-    /*Copy the rendered image to the screen.
+    /* Copy rendered image to screen.
-     *It needs to be implemented by the user*/
+     * This needs to be implemented by the user. */
     void my_flush_cb(lv_display_t * disp, const lv_area_t * area, uint8_t * px_buf)
     {
-        /*Show the rendered image on the display*/
+        /* Show the rendered image on the display */
         my_display_update(area, px_buf);
 
-        /*Indicate that the buffer is available.
+        /* Indicate that the buffer is available.
-         *If DMA were used, call in the DMA complete interrupt*/
+         * If DMA were used, call in the DMA complete interrupt. */
         lv_display_flush_ready();
     }
 
 
+
 .. _basics_displays:
 
 Displays
@@ -113,6 +123,8 @@ display from scratch as well (as shown above).
 
 LVGL also handles multiple displays at once.
 
+
+
 .. _basics_screens:
 
 Screens
@@ -130,6 +142,8 @@ The most common way to create a screen is by creating a :ref:`Base widget <base_
 
 A screen can be loaded like this: :cpp:expr:`lv_screen_load(my_screen)`
 
+
+
 .. _basics:widgets:
 
 Widgets
@@ -164,20 +178,21 @@ Here is an example that also shows some non-pixel units for sizes:
 .. code-block:: c
 
     lv_obj_t * my_button1 = lv_button_create(lv_screen_active());
-    /*Set parent-sized width, and content-sized height*/
+    /* Set parent-sized width, and content-sized height */
     lv_obj_set_size(my_button1, lv_pct(100), LV_SIZE_CONTENT);
-    /*Align to the right center with 20px offset horizontally*/
+    /* Align to the right center with 20px offset horizontally */
     lv_obj_align(my_button1, LV_ALIGN_RIGHT_MID, -20, 0);
 
     lv_obj_t * my_label1 = lv_label_create(my_button1);
     lv_label_set_text_fmt(my_label1, "Click me!");
     lv_obj_set_style_text_color(my_label1, lv_color_hex(0xff0000), 0);
-    /*Make the text red*/
+    /* Make the text red */
 
 To see the full API for any widget, see its documentation at :ref:`widgets`, or check
 its related header file in the source code.
 
 
+
 .. _basics_events:
 
 Events
@@ -219,6 +234,8 @@ The Widget that triggered the event can be retrieved with:
 
 Learn all about Events in the :ref:`events` section.
 
+
+
 Parts and States
 ****************
 
@@ -237,6 +254,7 @@ of a widget.
 
 Read the Widget's documentation to learn which parts it uses.
 
+
 .. _basics_states:
 
 States
@@ -270,6 +288,8 @@ To programmatically add or remove states use:
    lv_obj_add_state(widget, LV_STATE_...);
    lv_obj_remove_state(widget, LV_STATE_...);
 
+
+
 .. _basics_styles:
 
 Styles
@@ -298,6 +318,7 @@ See :ref:`style_properties_overview` for more details.
 
 See :ref:`style_properties` to see the full list.
 
+
 Adding styles to the widgets
 ----------------------------
 
@@ -309,6 +330,7 @@ After that it can be added to widgets:
     lv_obj_add_style(my_checkbox1, &style1, LV_STATE_DISABLED); /*Add to checkbox's disabled state*/
     lv_obj_add_style(my_slider1, &style1, LV_PART_KNOB | LV_STATE_PRESSED); /*Add to the slider's knob pressed state*/
 
+
 Inheritance
 -----------
 
@@ -318,6 +340,7 @@ its parents. For example, you can set the font once in the screen's
 style and all text on that screen will inherit it by default, unless the
 font is specified on the widget or one of its parents.
 
+
 Local styles
 ------------
 
@@ -330,6 +353,8 @@ style which resides inside the Widget and is used only by that Widget:
 
 See :ref:`styles` for full details.
 
+
+
 .. _basics_subjects:
 
 Subjects and Observers

docs/src/intro/introduction/faq.rst

@@ -16,6 +16,7 @@ You should use them only if your question or issue is tightly related to the dev
 Before posting a question, please read this FAQ section since you might find the answer to your issue here as well.
 
 
+
 Is my MCU/hardware supported?
 *****************************
 
@@ -29,6 +30,7 @@ This includes:
 * Anything else with a strong enough MCU and a peripheral to drive a display
 
 
+
 Is my display supported?
 ************************
 
@@ -47,8 +49,9 @@ Some examples of the supported display types:
 See the :ref:`display` section to learn more.
 
 
-LVGL doesn't start, randomly crashes or nothing is drawn on the display. What can be the problem?
+
-*************************************************************************************************
+LVGL doesn't start, randomly crashes or nothing is drawn on the display. What might be the problem?
+***************************************************************************************************
 
 * Try increasing :c:macro:`LV_MEM_SIZE`.
 * Be sure your display works without LVGL. E.g. paint it to red on start up.
@@ -60,6 +63,7 @@ LVGL doesn't start, randomly crashes or nothing is drawn on the display. What ca
   * Be sure you are using one of the methods for thread management as described in :ref:`threading`.
 
 
+
 My display driver is not called. What have I missed?
 ****************************************************
 
@@ -70,11 +74,13 @@ Be sure you are calling :cpp:expr:`lv_tick_inc(x)` as prescribed in
 Learn more in the :ref:`tick_interface` and :ref:`timer_handler` sections.
 
 
+
 Why is the display driver called only once? Only the upper part of the display is refreshed.
 ********************************************************************************************
 
 Be sure you are calling :cpp:expr:`lv_display_flush_ready(drv)` at the end of your
-"*display flush callback*" as per :ref:`flush_callback` section.
+"*display flush callback*" as per the :ref:`flush_callback` section.
+
 
 
 Why do I see only garbage on the screen?
@@ -101,6 +107,7 @@ LVGL.  You should see a square with red-blue gradient.
     }
 
 
+
 Why do I see nonsense colors on the screen?
 *******************************************
 
@@ -108,6 +115,7 @@ The configured LVGL color format is probably not compatible with your display's
 format.  Check :c:macro:`LV_COLOR_DEPTH` in *lv_conf.h*.
 
 
+
 How do I speed up my UI?
 ************************
 
@@ -117,6 +125,11 @@ How do I speed up my UI?
 - Increase the clock speed of the SPI or parallel port if you use them to drive the display.
 - If your display has an SPI port consider changing to a model with a parallel interface because it has much higher throughput.
 - Keep the display buffer in internal RAM (not in external SRAM) because LVGL uses it a lot and it should have fast access time.
+- Consider minimizing LVGL CPU overhead by updating Widgets:
+
+  - only once just before each display refresh, and
+  - only when it will change what the end user sees.
+
 
 
 How do I reduce flash/ROM usage?
@@ -127,12 +140,14 @@ You can disable unused features (such as animations, file system, GPU etc.) and
 If you are using GCC/CLANG you can add `-fdata-sections -ffunction-sections` compiler flags and `--gc-sections` linker flag to remove unused functions and variables from the final binary. If possible, add the `-flto` compiler flag to enable link-time-optimisation together with `-Os` for GCC or `-Oz` for CLANG and newer GCC versions.
 
 
+
 How do I reduce RAM usage?
 **************************
 
 * Lower the size of the *Display buffer*.
 * Reduce :c:macro:`LV_MEM_SIZE` in *lv_conf.h*. This memory is used when you create Widgets like buttons, labels, etc.
-* To work with lower :c:macro:`LV_MEM_SIZE` you can create Widgets only when required and delete them when they are not needed anymore.
+* To work with lower :c:macro:`LV_MEM_SIZE` you can create Widgets only when required and delete them when they are no longer needed.
+
 
 
 How do I use LVGL with an operating system?

docs/src/intro/introduction/repo.rst

@@ -10,12 +10,12 @@ Repository layout
 
 All repositories of the LVGL project are hosted on `GitHub <https://github.com/lvgl>`_.
 
-You will find these repositories there:
+You will find these repositories at the following locations:
 
 * `lvgl <https://github.com/lvgl/lvgl>`__: The library itself with many `examples <https://github.com/lvgl/lvgl/blob/master/examples/>`_ and `demos <https://github.com/lvgl/lvgl/blob/master/demos/>`__.
 * `blog <https://github.com/lvgl/blog>`__: Source of the `blog's site <https://blog.lvgl.io>`__
 * `sim <https://github.com/lvgl/sim>`__: Source of the `online simulator's site <https://sim.lvgl.io>`__
-* `lv_port_* <https://github.com/lvgl?q=lv_port&type=&language=>`__: LVGL ports to development boards or environments
+* `lv_port_* <https://github.com/lvgl?q=lv_port&type=&language=>`__: LVGL ports to development boards and other platforms
 * `lv_binding_* <https://github.com/lvgl?q=lv_binding&type=&language=l>`__: Bindings to other languages
 
 

docs/src/intro/introduction/requirements.rst

@@ -12,12 +12,12 @@ run LVGL.  The minimal requirements are:
 * Flash/ROM: > 64 kB for the very essential components (> 180 kB is recommended)
 * RAM:
 
-  * Static RAM usage: ~2 kB depending on the used features and Widget types
+    * Static RAM usage: ~2 kB depending on the used features and Widget types
-  * stack: > 2kB (> 8 kB recommended)
+    * stack: > 2kB (> 8 kB recommended)
-  * Dynamic data (heap): > 2 KB (> 48 kB is recommended if using many GUI Widgets).
+    * Dynamic data (heap): > 2 KB (> 48 kB is recommended if using many GUI Widgets).
-    Set by :c:macro:`LV_MEM_SIZE` in ``lv_conf.h``.
+      Set by :c:macro:`LV_MEM_SIZE` in ``lv_conf.h``.
-  * Display buffer:  > *"Horizontal resolution"* pixels (> 10 X *"Horizontal resolution"* is recommended)
+    * Display buffer:  > *"Horizontal resolution"* pixels (> 10 X *"Horizontal resolution"* is recommended)
-  * One frame buffer in the MCU or in an external display controller
+    * One frame buffer in the MCU or in an external display controller
 
 * C99 or newer compiler
 * Basic C (or C++) knowledge: