docs(intro): improve initial presentation of LVGL... (#8597)

docs/src/index.rst

@@ -94,29 +94,3 @@ Appendix
     CHANGELOG
     API/index
 
-
-.. The below toctree directive is merely to eliminate 2 Sphinx warnings that these 2
-   files are "not included in any toctree".  Their sole purpose is so that any reader
-   noticing the URL structure and (as an experiment) browsing to
-
-   https://docs.lvgl.io/master/intro/
-
-   or
-
-   https://docs.lvgl.io/master/details/
-
-   will not be met by a 404 (File not found) error from the docs server.
-
-   Note:  this must be accompanied by "'includehidden': False" in `conf.py` in the
-   `html_theme_options` dictionary so that these 2 files do not appear as redundant
-   entries in the top-level navigation tree.  (This is the only toctree directive
-   with the :hidden: attribute.)
-
-.. Commenting out the below for Furo theme.
-    .. toctree::
-        :hidden:
-
-        intro/index
-        details/index
-
-

docs/src/intro/introduction/index.rst

@@ -4,19 +4,59 @@
 Introduction
 ============
 
-LVGL (Light and Versatile Graphics Library) is a free and open-source graphics
+LVGL (Light and Versatile Graphics Library) is a free and open-source C graphics
 library providing everything you need to create an embedded GUI with easy-to-use
 graphical elements, beautiful visual effects, and a low memory footprint.
 
-You :ref:`add LVGL to your project <adding_lvgl_to_your_project>`, provide it with
-inputs and the method for pixels to flow to the display panel(s), and LVGL does the
-heavy lifting in between.
+LVGL provides the "GUI engine" that handles all end-user interaction with your
+application, including not only drawing the contents of the display and accepting
+user input and turning it into events "catchable" by the application, but also
+providing 30+ built-in widgets, 100+ style properties, scrolling, animations,
+advanced software rendering, built-in GPU support from MCUs to OpenGL, and much more.
+The combination of these enable you to efficiently develop UIs without having to
+re-invent the wheel.
+
+Using LVGL in a firmware project effectively reduces the GUI-developer's job to
+defining the GUI and furnishing it with appropriate event hooks to carry out the
+valuable work of the GUI.
+
+LVGL can use GUIs that are 100% defined in C code you write (for which any updates to
+the GUI require modifying that C code and re-flashing the firmware), or GUI
+definitions provided in XML files (for which updates to the GUI require only
+modifying the XML files that define the GUI for that firmware), or any combination of
+these two that suits your project.
+
+
+
+.. _key_features:
+
+Key Features
+************
+
+- Powerful building blocks such as :ref:`buttons, charts, lists, sliders, images <widgets>`, etc.
+- Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling
+- Various input devices such as touchpad, mouse, keyboard, encoder, etc.
+- Multi-language support with UTF-8 encoding
+- Multi-display support, even with mixed color formats
+- Fully customizable graphic elements with CSS-like styles
+- Hardware independent:  use with any microcontroller or display
+- Scalable: able to operate with little memory (64 kB Flash, 16 kB RAM)
+- :ref:`OS <threading>`, external memory and :ref:`GPU <draw>` are supported but not required
+- Single frame buffer operation even with advanced graphic effects
+- Written in C for maximal compatibility (C++ compatible)
+- :ref:`Simulator <simulator>` to start embedded GUI design on a PC without embedded hardware
+- User code developed under simulator can be shared with firmware to make UI development more efficient.
+- Binding to :ref:`MicroPython`
+- Tutorials, examples, themes for rapid GUI design
+- Documentation is available online
+- Free and open-source under MIT license
+- Free for commercial projects
+
 
 
 .. toctree::
     :maxdepth: 2
 
-    key_features
     requirements
     license
     faq

docs/src/intro/introduction/key_features.rst

@@ -1,25 +0,0 @@
-.. _key_features:
-
-============
-Key features
-============
-
-- Powerful building blocks such as :ref:`buttons, charts, lists, sliders, images <widgets>`, etc.
-- Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling
-- Various input devices such as touchpad, mouse, keyboard, encoder, etc.
-- Multi-language support with UTF-8 encoding
-- Multi-display support, even with mixed color formats
-- Fully customizable graphic elements with CSS-like styles
-- Hardware independent:  use with any microcontroller or display
-- Scalable: able to operate with little memory (64 kB Flash, 16 kB RAM)
-- :ref:`OS <threading>`, external memory and :ref:`GPU <draw>` are supported but not required
-- Single frame buffer operation even with advanced graphic effects
-- Written in C for maximal compatibility (C++ compatible)
-- :ref:`Simulator <simulator>` to start embedded GUI design on a PC without embedded hardware
-- User code developed under simulator can be shared with firmware to make UI development more efficient.
-- Binding to :ref:`MicroPython`
-- Tutorials, examples, themes for rapid GUI design
-- Documentation is available online
-- Free and open-source under MIT license
-
-

docs/src/intro/introduction/requirements.rst

@@ -11,17 +11,20 @@ run LVGL.  The minimal requirements are:
 * > 16 MHz clock speed is recommended
 * 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
-    * stack: > 2kB (> 8 kB recommended)
-    * 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``.
-    * Display buffer:  > *"Horizontal resolution"* pixels (> 10 X *"Horizontal resolution"* is recommended)
-    * One frame buffer in the MCU or in an external display controller
+
+  * Static RAM usage: ~2 kB depending on the used features and Widget types
+  * stack: > 2kB (> 8 kB recommended)
+  * 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``.
+  * Display buffer:  > *"Horizontal resolution"* pixels (> 10 X *"Horizontal resolution"* is recommended)
+  * One frame buffer in the MCU or in an external display controller
+
 * C99 or newer compiler
 * Basic C (or C++) knowledge:
-    * `pointers <https://www.tutorialspoint.com/cprogramming/c_pointers.htm>`__.
-    * `structs <https://www.tutorialspoint.com/cprogramming/c_structures.htm>`__.
-    * `callbacks <https://www.geeksforgeeks.org/callbacks-in-c/>`__.
+
+  * `pointers <https://www.tutorialspoint.com/cprogramming/c_pointers.htm>`__.
+  * `structs <https://www.tutorialspoint.com/cprogramming/c_structures.htm>`__.
+  * `callbacks <https://www.geeksforgeeks.org/callbacks-in-c/>`__.
 
 .. note::
     *Memory usage may vary depending on architecture, compiler and build options.*