diff --git a/docs/example_list.py b/docs/example_list.py index add11d3091..350a936567 100755 --- a/docs/example_list.py +++ b/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]) diff --git a/examples/porting/osal/index.rst b/examples/porting/osal/index.rst new file mode 100644 index 0000000000..3e82274d6a --- /dev/null +++ b/examples/porting/osal/index.rst @@ -0,0 +1,7 @@ + +Basic Example +------------- + +.. lv_example:: porting/osal/lv_example_osal + :language: c +