docs(examples): fix libs/, others/ and porting/ missing from examples page. (#9291)

docs/example_list.py

@@ -1,5 +1,149 @@
 #!/usr/bin/env python3
+""" example_list.py -- Gather all examples under ``lvgl/examples/`` into ``examples.rst``.
+
+"Examples" are defined by the presence of an ``index.rst`` in a directory with
+example code in a file starting with "lv_example_".  That C code is pulled into
+each example in the EXAMPLES HTML page, as well as everywhere such examples are
+included by putting a directive like this in the doc:
+
+    .. include:: /examples/layouts/flex/index.rst
+
+Note that in the intermediate dir (from which LVGL user docs are generated),
+``./examples/`` is a top-level subdirectory, so no relative "../../.." etc.
+is required in the path.  Using a path starting at "root" tells Sphinx to
+start at the top-level directory where the docs are being generated,
+typically ``lvgl/docs/intermediate/``.
+
+See `build.py` for more information about the intermediate directory.
+"""
+
 import os
+import sys
+
+# -------------------------------------------------------------------------
+# The below are a set of section headings that will be used in ``examples.rst``.
+# The key value must match subdirectory names found under ``lvgl/examples/``.
+# The entries in `chapter_section_headings` define the sequence of the
+# top-level chapter headings in ``examples.rst``.
+# -------------------------------------------------------------------------
+# Directories under ``lvgl/examples/`` containing ``index.rst`` files (directly and indirectly)
+chapter_section_headings = {
+    "get_started"  : "Get Started",
+    "styles"       : "Styles",
+    "anim"         : "Animations",
+    "event"        : "Events",
+    "layouts"      : "Layouts",
+    "scroll"       : "Scrolling",
+    "widgets"      : "Widgets",
+    "libs"         : "3rd-Party Libraries",
+    "others"       : "Others",
+    "porting"      : "Porting",
+}
+
+# Directories under ``lvgl/examples/layouts/`` containing ``index.rst`` files
+layouts_section_headings = {
+    "flex"         : "Flex",
+    "grid"         : "Grid",
+}
+
+# Directories under ``lvgl/examples/widgets/`` containing ``index.rst`` files
+widgets_section_headings = {
+    "obj"          : "Base Widget",
+    "animimg"      : "Animation Image",
+    "arc"          : "Arc",
+    "arclabel"     : "Arc Label",
+    "bar"          : "Bar",
+    "button"       : "Button",
+    "buttonmatrix" : "Button Matrix",
+    "calendar"     : "Calendar",
+    "canvas"       : "Canvas",
+    "chart"        : "Chart",
+    "checkbox"     : "Checkbox",
+    "dropdown"     : "Dropdown",
+    "image"        : "Image",
+    "imagebutton"  : "Image Button",
+    "keyboard"     : "Keyboard",
+    "label"        : "Label",
+    "led"          : "LED",
+    "line"         : "Line",
+    "list"         : "List",
+    "lottie"       : "Lottie",
+    "menu"         : "Menu",
+    "msgbox"       : "Message Box",
+    "roller"       : "Roller",
+    "scale"        :"Scale",
+    "slider"       : "Slider",
+    "span"         : "Span",
+    "spinbox"      : "Spinbox",
+    "spinner"      : "Spinner",
+    "switch"       : "Switch",
+    "table"        : "Table",
+    "tabview"      : "Tabview",
+    "textarea"     : "Textarea",
+    "tileview"     : "Tileview",
+    "win"          : "Window",
+}
+
+# Directories under ``lvgl/examples/libs/`` containing ``index.rst`` files
+libs_section_headings = {
+    "barcode"      : "Barcode",
+    "bmp"          : "BMP",
+    "ffmpeg"       : "FFmpeg",
+    "freetype"     : "FreeType",
+    "gif"          : "GIF",
+    "gltf"         : "glTF",
+    "gstreamer"    : "GStreamer",
+    "libjpeg_turbo": "libjpeg-turbo",
+    "libpng"       : "libpng",
+    "libwebp"      : "LibWebP",
+    "lodepng"      : "LodePNG",
+    "qrcode"       : "QR-Code Generator",
+    "rlottie"      : "rlottie",
+    "svg"          : "SVG",
+    "tiny_ttf"     : "Tiny TTF",
+    "tjpgd"        : "Tiny JPEG Decompressor (TJpgDec)",
+}
+
+# Directories under ``lvgl/examples/others/`` containing ``index.rst`` files
+others_section_headings = {
+    "file_explorer": "File Explorer",
+    "font_manager" : "Font Manager",
+    "fragment"     : "Fragment Manager",
+    "gestures"     : "Gestures",
+    "gridnav"      : "Grid Navigation",
+    "ime"          : "Pinyin IME",
+    "imgfont"      : "Image Font",
+    "monkey"       : "Monkey",
+    "observer"     : "Observer",
+    "snapshot"     : "Snapshot",
+    "translation"  : "Translation",
+    "xml"          : "XML Components",
+}
+
+# Directories under ``lvgl/examples/porting/`` containing ``index.rst`` files
+porting_section_headings = {
+    "osal"         : "OS Abstraction Layer (OSAL)",
+}
+
+# -------------------------------------------------------------------------
+# This is the order that LVGL documentation uses for the section heading
+# levels.  0 is the largest and 4 is the smallest.  If this order is not
+# kept in the reST files Sphinx will complain, and have difficulty
+# formatting the TOC correctly.
+# -------------------------------------------------------------------------
+HEADING = '='
+CHAPTER = '*'
+SECTION = '-'
+SUBSECTION = '~'
+SUBSUBSECTION = '^'
+
+header_defs = {
+    0: HEADING,
+    1: CHAPTER,
+    2: SECTION,
+    3: SUBSECTION,
+    4: SUBSUBSECTION
+}
 
 
 def process_index_rst(path):
@@ -28,61 +172,14 @@ def process_index_rst(path):
         last_line = line
 
 
-h1 = {
-    "get_started": "Get Started",
-    "styles": "Styles",
-    "anim": "Animations",
-    "event": "Events",
-    "layouts": "Layouts",
-    "scroll": "Scrolling",
-    "widgets": "Widgets"
-}
-
-widgets = {
-    "obj": "Base Widget",
-    "animimg": "Animation Image",
-    "arc": "Arc",
-    "bar": "Bar",
-    "button": "Button",
-    "buttonmatrix": "Button Matrix",
-    "calendar": "Calendar",
-    "canvas": "Canvas",
-    "chart": "Chart",
-    "checkbox": "Checkbox",
-    "dropdown": "Dropdown",
-    "image": "Image",
-    "imagebutton": "Image Button",
-    "keyboard": "Keyboard",
-    "label": "Label",
-    "led": "LED",
-    "line": "Line",
-    "list": "List",
-    "lottie": "Lottie",
-    "menu": "Menu",
-    "msgbox": "Message Box",
-    "roller": "Roller",
-    "scale":"Scale",
-    "slider": "Slider",
-    "span": "Span",
-    "spinbox": "Spinbox",
-    "spinner": "Spinner",
-    "switch": "Switch",
-    "table": "Table",
-    "tabview": "Tabview",
-    "textarea": "Textarea",
-    "tileview": "Tileview",
-    "win": "Window",
-}
-
-HEADING = '='
-CHAPTER = '#'
-SECTION = '*'
-SUBSECTION = '='
-SUBSUBSECTION = '-'
-
-
 def write_header(h_num, text, f):
+    if h_num == 2:
+        f.write('\n')    # 1 extra blank line above sections
+    elif h_num == 1:
+        f.write('\n\n')  # 2 extra blank lines above chapters
+
     text = text.strip()
+
     if h_num == 0:
         f.write(header_defs[h_num] * len(text))
         f.write('\n')
@@ -92,23 +189,6 @@ def write_header(h_num, text, f):
     f.write('\n\n')
 
 
-# This is the order that Sphinx uses for the headings/titles. 0 is the
-# largest and 4 is the smallest. If this order is not kept in the reST files
-# Sphinx will complain
-header_defs = {
-    0: HEADING,
-    1: CHAPTER,
-    2: SECTION,
-    3: SUBSECTION,
-    4: SUBSUBSECTION
-}
-
-layouts = {
-    "flex": "Flex",
-    "grid": "Grid",
-}
-
-
 def print_item(path, lvl, d, fout):
     for k in d:
         v = d[k]
@@ -118,20 +198,19 @@ def print_item(path, lvl, d, fout):
             fout.write("\n")
 
 
-def exec(temp_directory):
-    output_path = os.path.join(temp_directory, 'examples.rst')
-
+def exec(intermediate_dir):
+    output_path = os.path.join(intermediate_dir, 'examples.rst')
     paths = ["../examples/", "../demos/"]
     fout = open(output_path, "w")
     filelist = []
 
+    # Recursively walk the directories in `paths` array for ``index.rst`` files.
     for path in paths:
         for root, dirs, files in os.walk(path):
             for f in files:
                 # append the file name to the list
-                filelist.append(os.path.join(root, f))
-
-    filelist = [fi for fi in filelist if fi.endswith("index.rst")]
+                if f.endswith("index.rst"):
+                    filelist.append(os.path.join(root, f))
 
     d_all = {}
     # print all the file names
@@ -146,18 +225,42 @@ def exec(temp_directory):
     fout.write('.. _examples:\n\n')
     write_header(0, 'Examples', fout)
 
-    for h in h1:
-        write_header(1, h1[h], fout)
+    for chapter_hdg_key in chapter_section_headings:
+        write_header(1, chapter_section_headings[chapter_hdg_key], fout)
 
-        if h == "widgets":
-            for w in widgets:
-                write_header(2, widgets[w], fout)
-                print_item(h + "/" + w, 3, d_all, fout)
-        elif h == "layouts":
-            for l in layouts:
-                write_header(2, layouts[l], fout)
-                print_item(h + "/" + l, 3, d_all, fout)
+        # If an immediate subdirectory below ``lvgl/examples/`` itself has
+        # subdirectories before we get to any ``index.rst`` files, then that
+        # subdirectory requires an IF in the below IF/ELSE chain.  The final
+        # ELSE block handles subdirectories that directly contain ``index.rst``
+        # files with no subdirectories.
+        if chapter_hdg_key == "widgets":
+            for key in widgets_section_headings:
+                write_header(2, widgets_section_headings[key], fout)
+                print_item(chapter_hdg_key + "/" + key, 3, d_all, fout)
+        elif chapter_hdg_key == "layouts":
+            for key in layouts_section_headings:
+                write_header(2, layouts_section_headings[key], fout)
+                print_item(chapter_hdg_key + "/" + key, 3, d_all, fout)
+        elif chapter_hdg_key == "libs":
+            for key in libs_section_headings:
+                write_header(2, libs_section_headings[key], fout)
+                print_item(chapter_hdg_key + "/" + key, 3, d_all, fout)
+        elif chapter_hdg_key == "others":
+            for key in others_section_headings:
+                write_header(2, others_section_headings[key], fout)
+                print_item(chapter_hdg_key + "/" + key, 3, d_all, fout)
+        elif chapter_hdg_key == "porting":
+            for key in porting_section_headings:
+                write_header(2, porting_section_headings[key], fout)
+                print_item(chapter_hdg_key + "/" + key, 3, d_all, fout)
         else:
-            print_item(h, 2, d_all, fout)
+            print_item(chapter_hdg_key, 2, d_all, fout)
 
         fout.write("")
+
+
+if __name__ == '__main__':
+    """Make module run-able as well as importable."""
+    base_dir = os.path.abspath(os.path.dirname(__file__))
+    os.chdir(base_dir)
+    exec(sys.argv[1])