feat(docs): reorganize docs (lvgl#7136)

OS-Q · Oct 23, 2024 · 9b6f6d2 · 9b6f6d2
1 parent c61ca42
commit 9b6f6d2
Show file tree

Hide file tree

Showing 212 changed files with 6,313 additions and 5,805 deletions.
diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst
@@ -1,24 +1,24 @@
 .. _changelog:
 
-Changelog
-=========
+Change Log
+==========
 
 `v9.2 <https://github.com/lvgl/lvgl/compare/v9.1.0...v9.2.0>`__ 26 August 2024
 ------------------------------------------------------------------------------
 
 It's huge release with many interesting updates:
 
-- Built-in `Wayland driver <https://docs.lvgl.io/master/integration/driver/wayland.html>`__
-- `OpenGL ES and GLFW driver <https://docs.lvgl.io/master/integration/driver/opengles.html>`__ with support for external textures
-- `Renesas GLCDC <https://docs.lvgl.io/master/integration/driver/display/renesas_glcdc.html>`__ driver
+- Built-in :ref:`Wayland driver <wayland_driver>`
+- :ref:`OpenGL ES and GLFW driver <opengl_es_driver>` with support for external textures
+- :ref:`renesas_glcdc` driver
 - L8 and I1 rendering support
 - Matrix transformations during rendering
-- New `file system interfaces <https://docs.lvgl.io/master/libs/fs.html>`__: LittleFS, ESP LittleFS, Arduino FS
+- New :ref:`file system interfaces <libs_filesystem>`: LittleFS, ESP LittleFS, Arduino FS
 - SDL renderer improvements (supporting all draw task types and improving speed)
-- Radial, Conic, and Skew `gradients supported <https://docs.lvgl.io/master/overview/style.html#metallic-knob-with-conic-gradient>`__ by software rendering and VG-Lite
-- `QNX <https://docs.lvgl.io/master/integration/os/qnx.html>`__ and `MQX <https://docs.lvgl.io/master/integration/os/mqx.html>`__ support
-- `Mouse hover handling <https://docs.lvgl.io/master/get-started/quick-overview.html>`__
-- `Lottie <https://docs.lvgl.io/master/widgets/lottie.html>`__ support
+- Radial, Conic, and Skew `gradients supported <https://docs.lvgl.io/master/details/base-widget/styles/style.html#metallic-knob-with-conic-gradient>`__ by software rendering and VG-Lite
+- :ref:`qnx` and :ref:`mqx` support
+- :ref:`Mouse hover handling <styles_states>`
+- :ref:`lv_lottie` support
 - CI tests for UEFI builds
 
 And many smaller fixes and features

diff --git a/docs/CODING_STYLE.rst b/docs/CODING_STYLE.rst
@@ -148,7 +148,7 @@ illustrating most of the Doxygen commands used in LVGL.
 .. code-block:: c
 
     /**
-     * Set alignment of objects placed in containers with LV_STYLE_FLEX_FLOW style.
+     * Set alignment of Widgets placed in containers with LV_STYLE_FLEX_FLOW style.
      *
      * The values for the `..._place` arguments come from the `lv_flex_align_t`
      * enumeration and have the same meanings as they do for flex containers in CSS.
@@ -170,7 +170,7 @@ illustrating most of the Doxygen commands used in LVGL.
      *     - https://css-tricks.com/snippets/css/a-guide-to-flexbox/
      *     - see  `lv_obj_set_flex_grow()` for additional information.
      */
-    void lv_obj_set_flex_align(lv_obj_t * obj, lv_flex_align_t main_place, lv_flex_align_t cross_place,
+    void lv_obj_set_flex_align(lv_obj_t * widget, lv_flex_align_t main_place, lv_flex_align_t cross_place,
                                lv_flex_align_t track_cross_place);
 
 
@@ -264,12 +264,12 @@ follow some coding conventions:
 - Use typed pointers instead of :cpp:expr:`void *` pointers
 - Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
 - Widget members function must start with ``lv_<widget_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
-  argument which is a pointer to widget object itself.
+  argument which is a pointer to Widget object itself.
 - ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
   first argument, and the prefix of the ``struct`` name should be used as the prefix of the
-  function name too (e.g. :cpp:expr:`lv_display_set_default(lv_display_t * disp)`)
+  function name as well (e.g. :cpp:expr:`lv_display_set_default(lv_display_t * disp)`)
 - Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private".
-- Argument must be named in H files too.
+- Argument must be named in H files as well.
 - Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t``
   structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used.
 - To register and use callbacks one of the following needs to be followed.
@@ -293,7 +293,7 @@ Here is example to show bracket placing and using of white space:
    /**
     * Set new text for a label.  Memory will be allocated by label to store text.
     *
-    * @param  label  pointer to label object
+    * @param  label  pointer to label Widget
     * @param  text   '\0' terminated character string.
     *                NULL to refresh with current text.
     */

diff --git a/docs/README.md b/docs/README.md
@@ -52,7 +52,18 @@ The most important thing that has to be done when contributing to LVGL is ***EVE
 The below are some rules to follow when updating any of the `.rst` files located in the `./docs/` directory and any of it's subdirectories.
 
 
-### index.rst files
+### What to Name Your `.rst` File
+
+The documentation-generation logic uses the stem of the file name (i.e. "event" from file name "event.rst") and compares this with code-element names found by Doxygen.  If a match is found, then it appends hyperlinks to the API pages that contain those code elements (names of macros, enum/struct/union types, variables, namespaces, typedefs and functions).
+
+If this is appropriate for the .RST file you are creating, ensure the stem of the file name matches the beginning part of the code-element name you want it to be associated with.
+
+If this is *not* appropriate for the .RST file you are creating, ensure the stem of the file name DOES NOT match any code-element names found in the LVGL header files under the ./src/ directory.
+
+In alignment with the above, use a file name stem that is appropriate to the topic being covered.
+
+
+### index.rst Files
 
 If you create a new directory you MUST have an `index.rst` file in that directory and that index file needs to be pointed to in the `index.rst` file that is located in the parent directory.
 
@@ -124,6 +135,8 @@ This in-line markup (interpreted text using the Sphinx-defined custom `:ref:` ro
 
 This latter syntax enables you to put a **link target** anywhere in an .RST file (not just above a heading) and link to it using this syntax.
 
+Note:  This latter syntax was either added or fixed in Sphinx recently.  It did not work in Sphinx 7.3.7.
+
 
 
 
@@ -144,19 +157,19 @@ If you are creating a new .RST file, use this convention:
     =====
     Title
     =====
-    
+
     Chapter
     *******
-    
+
     Section
     -------
-    
+
     Sub Section
     ~~~~~~~~~~~
-    
+
     Sub Sub Section
     ^^^^^^^^^^^^^^^
-    
+
     Sub Sub Sub Section
     '''''''''''''''''''
 
@@ -201,7 +214,7 @@ To create a bulleted list, do the following:
       lines to align with item text like this.
     - If you want to include a code block under a list item,
       it must be intended to align with the list item like this:
-    
+
       .. code-block: python
                                  <=== blank line here is important
           # this is some code
@@ -232,22 +245,23 @@ If you want to reference portions of the LVGL code from the documentation (in .R
 
 There is a special directive when wanting to use a more complex expression.  For example when showing the arguments passed to a function.
 
-    :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`
+    :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX)`
+    :cpp:expr:`lv_slider_set_mode(slider, LV_SLIDER_MODE_...)`
 
 Arguments that are expressions (more than one word), or contain non-alphanumeric characters will cause the `:cpp:expr:` interpreted-text to fail.  Examples:
 
-    :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX/GRID)`         <== arg with > 1 word
-    :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_*)`                 <== asterisk
-    :cpp:expr:`lv_obj_set_layout(*obj, LV_LAYOUT_FLEX)`             <== asterisk
-    :cpp:expr:`lv_obj_set_layout((lv_obj_t *)obj, LV_LAYOUT_FLEX)`  <== cast
-    :cpp:expr:`lv_obj_set_layout(&obj, LV_LAYOUT_FLEX);`            <== ampersand
-    :cpp:expr:`lv_obj_set_layout(obj, ...)`                         <== elipsis
+    :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)`         <== arg with > 1 word
+    :cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_*)`                 <== asterisk
+    :cpp:expr:`lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)`             <== asterisk
+    :cpp:expr:`lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)`  <== cast
+    :cpp:expr:`lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);`            <== ampersand & semicolon
+    :cpp:expr:`lv_obj_set_layout(widget, ...)`                         <== lone elipsis
 
 For such examples, simply use reStructuredText literal markup like this:
 
-    ``lv_obj_set_layout(obj, LV_LAYOUT_FLEX/GRID)``
-    ``lv_obj_set_layout(obj, LV_LAYOUT_*)``
-    ``lv_obj_set_layout(*obj, LV_LAYOUT_FLEX)``
-    ``lv_obj_set_layout((lv_obj_t *)obj, LV_LAYOUT_FLEX)``
-    ``lv_obj_set_layout(&obj, LV_LAYOUT_FLEX);``
-    ``lv_obj_set_layout(obj, ...)``
+    ``lv_obj_set_layout(widget, LV_LAYOUT_FLEX/GRID)``
+    ``lv_obj_set_layout(widget, LV_LAYOUT_*)``
+    ``lv_obj_set_layout(*widget, LV_LAYOUT_FLEX)``
+    ``lv_obj_set_layout((lv_obj_t *)widget, LV_LAYOUT_FLEX)``
+    ``lv_obj_set_layout(&widget, LV_LAYOUT_FLEX);``
+    ``lv_obj_set_layout(widget, ...)``
diff --git a/docs/README_jp.rst b/docs/README_jp.rst
@@ -75,16 +75,16 @@ Cライブラリ。(C++互換) -
 任意の(RT)OS、任意のMCU・MPU用にコンパイル可能。 -
 電子ペーパー、OLEDディスプレイ、TFTディスプレイ、白黒ディスプレイ、モニターに対応。
 `Porting
-Guide <https://docs-lvgl-io.translate.goog/master/porting/project.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+Guide <https://docs-lvgl-io.translate.goog/master/intro/add-lvgl-to-your-project/project.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - MITライセンスにより商用利用可能。 - システム要件：RAM 32KB、Flash
 128KB、フレームバッファ、レンダリング用に1/10以上のスクリーンサイズのバッファ。
 - OS、外部メモリ、GPUもサポート。
 
 **ウィジェット、スタイル、レイアウトなど** - 30以上の組み込み
-`ウィジェット <https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__: ボタン、ラベル、スライダー、グラフ、キーボード、メーター、円弧、表など。
+`ウィジェット <https://docs-lvgl-io.translate.goog/master/details/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__: ボタン、ラベル、スライダー、グラフ、キーボード、メーター、円弧、表など。
 -
 ウィジェットの任意の部分を任意の状態にカスタマイズ可能な豊富なスタイルプロパティを備えた柔軟な
-`スタイルシステム <https://docs-lvgl-io.translate.goog/master/overview/style.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ 。
+`スタイルシステム <https://docs-lvgl-io.translate.goog/master/details/base-widget/styles/style.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__\ 。
 -
 `Flexbox <https://docs-lvgl-io.translate.goog/master/layouts/flex.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 および
@@ -98,19 +98,19 @@ Guide <https://docs-lvgl-io.translate.goog/master/porting/project.html?_x_tr_sl=
 アニメーション、アンチエイリアシング、不透明度、スムーズスクロール、シャドウ、画像変換などをサポートするレンダリングエンジン。
 -
 マウス、タッチパッド、キーパッド、キーボード、外部ボタン、エンコーダ等の
-`入力デバイス <https://docs-lvgl-io.translate.goog/master/porting/indev.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+`入力デバイス <https://docs-lvgl-io.translate.goog/master/details/modules/indev.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 をサポート。 -
-`マルチディスプレイ <https://docs-lvgl-io.translate.goog/master/overview/display.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+`マルチディスプレイ <https://docs-lvgl-io.translate.goog/master/details/modules/display.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 対応。
 
 **Binding と Build をサポート** - `MicroPython
 Binding <https://blog-lvgl-io.translate.goog/2019-02-20/micropython-bindings?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 が LVGL API を公開。 -
 カスタムビルドシステムは使用せず、プロジェクトの他のファイルをビルドするときに、LVGLをビルド可能。
 - Make と
-`CMake <https://docs-lvgl-io.translate.goog/master/get-started/platforms/cmake.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+`CMake <https://docs-lvgl-io.translate.goog/master/details/integration/building/cmake.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 が含まれており、すぐ使えるようにサポート。 -
-`PCのシミュレータで開発したUIコード <https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+`PCのシミュレータで開発したUIコード <https://docs-lvgl-io.translate.goog/master/details/integration/ide/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 は、そのまま組込み用ハードウェアでも使用可能。 - `Emscripten
 port <https://github.com/lvgl/lv_web_emscripten>`__ :gb:
 によりC言語のUIコードをHTMLファイルに変換。
@@ -128,19 +128,19 @@ UI開発をよりシンプルかつ迅速にするための、ユーザーイン
 --------------------
 
 LVGL は以下で利用可能です。 - `Arduino
-library <https://docs-lvgl-io.translate.goog/master/get-started/platforms/arduino.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+library <https://docs-lvgl-io.translate.goog/master/details/entegration/framework/arduino.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - `PlatformIO
 package <https://registry.platformio.org/libraries/lvgl/lvgl>`__ :gb: -
 `Zephyr
 library <https://docs-zephyrproject-org.translate.goog/latest/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - `ESP32
-component <https://docs-lvgl-io.translate.goog/master/get-started/platforms/espressif.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+component <https://docs-lvgl-io.translate.goog/master/details/integration/chip/espressif.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - `NXP MCUXpresso
 component <https://www-nxp-com.translate.goog/design/software/embedded-software/lvgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - `NuttX
-library <https://docs-lvgl-io.translate.goog/master/get-started/os/nuttx.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+library <https://docs-lvgl-io.translate.goog/master/details/integration/os/nuttx.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - `RT-Thread
-RTOS <https://docs-lvgl-io.translate.goog/master/get-started/os/rt-thread.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+RTOS <https://docs-lvgl-io.translate.goog/master/details/integration/os/rt-thread.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
 - NXP MCUXpresso library - CMSIS-Pack
 
 :robot:
@@ -386,7 +386,7 @@ C code
    /*Add the style sheet to the slider's INDICATOR part*/
    lv_obj_add_style(slider, &style_indicator, LV_PART_INDICATOR);
 
-   /*Add the same style to the KNOB part too and locally overwrite some properties*/
+   /*Add the same style to the KNOB part as well and locally overwrite some properties*/
    lv_obj_add_style(slider, &style_indicator, LV_PART_KNOB);
 
    lv_obj_set_style_outline_color(slider, lv_color_hex(0x0096FF), LV_PART_KNOB);
@@ -441,7 +441,7 @@ MicroPython code \| Online Simulator :gb:
    slider.add_style(style_indicator, lv.PART.INDICATOR)
    slider.add_style(style_indicator, lv.PART.KNOB)
 
-   # Add the same style to the KNOB part too and locally overwrite some properties
+   # Add the same style to the KNOB part as well and locally overwrite some properties
    slider.set_style_outline_color(lv.color_hex(0x0096FF), lv.PART.KNOB)
    slider.set_style_outline_width(3, lv.PART.KNOB)
    slider.set_style_outline_pad(-5, lv.PART.KNOB)
@@ -556,27 +556,27 @@ LVGLを使い始める時は、以下の順に進める事をおすすめしま
    `Introduction <https://docs-lvgl-io.translate.goog/master/intro/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
    を読みましょう。 (5分間)
 3. LVGLの基本に慣れるため `Quick
-   overview <https://docs-lvgl-io.translate.goog/master/get-started/quick-overview.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+   overview <https://docs-lvgl-io.translate.goog/master/intro/overview.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
    を読みましょう。 (15分間)
 
 **LVGLを使ってみましょう**
 
-4. `シミュレータ <https://docs-lvgl-io.translate.goog/master/get-started/platforms/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+4. `シミュレータ <https://docs-lvgl-io.translate.goog/master/details/integration/ide/pc-simulator.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
    をセットアップしましょう。 (10 minutes)
 5. `サンプルプログラム <https://github.com/lvgl/lvgl/tree/master/examples>`__
    :gb: を動かしてみましょう。
-6. `移植ガイド <https://docs-lvgl-io.translate.goog/master/porting/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+6. `移植ガイド <https://docs-lvgl-io.translate.goog/master/intro/add-lvgl-to-your-project/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
    を参考に、LVGLを開発ボードに移植してみましょう。すぐ使える形の
    `プロジェクト <https://github.com/lvgl?q=lv_port_>`__ :gb:
    も用意してあります。
 
 **より詳しく体験してみましょう**
 
 7. ライブラリの理解を深めるため
-   `Overview <https://docs-lvgl-io.translate.goog/master/overview/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+   `Overview <https://docs-lvgl-io.translate.goog/master/details/modules/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
    を読みましょう。 (2～3時間)
 8. ウィジェットの機能や使い方の詳細は
-   `Widgets <https://docs-lvgl-io.translate.goog/master/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
+   `Widgets <https://docs-lvgl-io.translate.goog/master/details/widgets/index.html?_x_tr_sl=en&_x_tr_tl=ja&_x_tr_hl=ja>`__
    でご確認ください。
 
 **助け合いましょう**