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

docs/example_list.py

@@ -1,47 +1,57 @@
 #!/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
 
-
+# -------------------------------------------------------------------------
-def process_index_rst(path):
+# The below are a set of section headings that will be used in ``examples.rst``.
-    #  print(path)
+# The key value must match subdirectory names found under ``lvgl/examples/``.
-    with open(path, 'r') as fp:
+# The entries in `chapter_section_headings` define the sequence of the
-        data = fp.read()
+# top-level chapter headings in ``examples.rst``.
-
+# -------------------------------------------------------------------------
-    data = data.split('\n')
+# Directories under ``lvgl/examples/`` containing ``index.rst`` files (directly and indirectly)
-
+chapter_section_headings = {
-    last_line = ""
-    title_tmp = ""
-
-    for line in data:
-        line = line.strip()
-
-        if not line:
-            continue
-
-        if line.startswith('---'):
-            title_tmp = last_line.strip()
-
-        elif line.startswith('.. lv_example::'):
-            name = line.replace('.. lv_example::', '').strip()
-            yield name, title_tmp
-
-        last_line = line
-
-
-h1 = {
     "get_started"  : "Get Started",
     "styles"       : "Styles",
     "anim"         : "Animations",
     "event"        : "Events",
     "layouts"      : "Layouts",
     "scroll"       : "Scrolling",
-    "widgets": "Widgets"
+    "widgets"      : "Widgets",
+    "libs"         : "3rd-Party Libraries",
+    "others"       : "Others",
+    "porting"      : "Porting",
 }
 
-widgets = {
+# 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",
@@ -74,27 +84,59 @@ widgets = {
     "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 = '#'
+CHAPTER = '*'
-SECTION = '*'
+SECTION = '-'
-SUBSECTION = '='
+SUBSECTION = '~'
-SUBSUBSECTION = '-'
+SUBSUBSECTION = '^'
 
-
-def write_header(h_num, text, f):
-    text = text.strip()
-    if h_num == 0:
-        f.write(header_defs[h_num] * len(text))
-        f.write('\n')
-
-    f.write(text + '\n')
-    f.write(header_defs[h_num] * len(text))
-    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,
@@ -103,10 +145,48 @@ header_defs = {
     4: SUBSUBSECTION
 }
 
-layouts = {
+
-    "flex": "Flex",
+def process_index_rst(path):
-    "grid": "Grid",
+    #  print(path)
-}
+    with open(path, 'r') as fp:
+        data = fp.read()
+
+    data = data.split('\n')
+
+    last_line = ""
+    title_tmp = ""
+
+    for line in data:
+        line = line.strip()
+
+        if not line:
+            continue
+
+        if line.startswith('---'):
+            title_tmp = last_line.strip()
+
+        elif line.startswith('.. lv_example::'):
+            name = line.replace('.. lv_example::', '').strip()
+            yield name, title_tmp
+
+        last_line = line
+
+
+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')
+
+    f.write(text + '\n')
+    f.write(header_defs[h_num] * len(text))
+    f.write('\n\n')
 
 
 def print_item(path, lvl, d, fout):
@@ -118,21 +198,20 @@ def print_item(path, lvl, d, fout):
             fout.write("\n")
 
 
-def exec(temp_directory):
+def exec(intermediate_dir):
-    output_path = os.path.join(temp_directory, 'examples.rst')
+    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
+                if f.endswith("index.rst"):
                     filelist.append(os.path.join(root, f))
 
-    filelist = [fi for fi in filelist if fi.endswith("index.rst")]
-
     d_all = {}
     # print all the file names
     for fn in filelist:
@@ -146,18 +225,42 @@ def exec(temp_directory):
     fout.write('.. _examples:\n\n')
     write_header(0, 'Examples', fout)
 
-    for h in h1:
+    for chapter_hdg_key in chapter_section_headings:
-        write_header(1, h1[h], fout)
+        write_header(1, chapter_section_headings[chapter_hdg_key], fout)
 
-        if h == "widgets":
+        # If an immediate subdirectory below ``lvgl/examples/`` itself has
-            for w in widgets:
+        # subdirectories before we get to any ``index.rst`` files, then that
-                write_header(2, widgets[w], fout)
+        # subdirectory requires an IF in the below IF/ELSE chain.  The final
-                print_item(h + "/" + w, 3, d_all, fout)
+        # ELSE block handles subdirectories that directly contain ``index.rst``
-        elif h == "layouts":
+        # files with no subdirectories.
-            for l in layouts:
+        if chapter_hdg_key == "widgets":
-                write_header(2, layouts[l], fout)
+            for key in widgets_section_headings:
-                print_item(h + "/" + l, 3, d_all, fout)
+                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])

examples/porting/osal/index.rst

@@ -0,0 +1,7 @@
+
+Basic Example
+-------------
+
+.. lv_example:: porting/osal/lv_example_osal
+  :language: c
+