Ricardo/Reflow-plate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First commit with working display

Browse Source
This commit is contained in:
Ricardo LAP
2026-09-13 20:50:51 +00:00
parent a83af259b3
commit c54c68c899
6690 changed files with 1093387 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

561
managed_components/lvgl__lvgl/docs/example_list.py Normal file
View File

@@ -0,0 +1,561 @@
#!/usr/bin/env python3
""" example_list.py -- Build `examples.rst`
`examples.rst` is built by gathering all examples recursively under
`lvgl/examples/`. The recognized directives in that file are then
processed by Sphinx using `lvgl/docs/src/_ext/lv_example.py`.
Subsection names within `examples.rst` are made up of the capitalized
directory names ('_' and '-' characters are converted to spaces) or
are spelled out in `index.rst` files if the subsection names should be
spelled differently. See "index.rst Format" section below for details.
An "example" is defined as:
- being anywhere under the `lvgl/examples/` directory,
- the presence of an `index.rst` in a directory with examples, and
- example C code in file names typically starting with "lv_example_".
That C code and a live, interactive running example, is pulled into each
example in the EXAMPLES HTML page, as well as every doc where such
examples are included, by a directive like this:
.. code::
.. 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.
If a subdirectory is included in the `avoid_dirs` list herein, it will
not generate any output in the resulting `examples.rst` file.
Example: `lvgl/examples/assets/`.
Usage
*****
.. code::
import example_list
example_list.make_warnings_into_errors() # Optional
example_list.DEBUG_MODE = True # Optional
example_list.exec(intermediate_dir)
or run it directly:
.. code:: bash
python3 example_list.py "/home/lvgl/docs/intermediate"
In both cases, the `intermediate_dir` passed is expected to have
an `./examples/` directory in it (copy of `lvgl/examples/`) as a
top-level subdirectory.
Examples Directory Requirements
*******************************
.. code:: text
lvgl/examples/
index.rst (.. dir_order: pseudo-directive since sub-dirs
are not presented in alphabetical order)
anim/
index.rst (see below for expected contents)
lv_example_anim_1.c
lv_example_anim_2.c
lv_example_anim_3.c
lv_example_anim_4.c
lv_example_anim_timeline_1.c
...
layouts/
flex/
index.rst (see below for expected contents)
lv_example_flex_1.c
lv_example_flex_2.c
lv_example_flex_3.c
etc.
grid/
etc.
libs/
index.rst (section-heading name: "3rd-Party Libraries"
[since it is different than parent directory name])
barcode/
index.rst (see below for expected contents)
lv_example_barcode_1.c
lv_example_barcode_1.h
bmp/
etc.
etc.
etc.
.. note:: The above shows only 2 levels of directories but deeper
levels are supported (up to 5 below document title).
index.rst Format
****************
Examples
--------
Examples are included in `index.rst` files when they are sibling files with
the example C code.
.. code::
Example 1 Title <-- required for each example
--------------- <-- required for each example
<-- blank lines are ignored
.. lv_example:: anim/lv_example_anim_1 <-- path relative to the `lvgl/examples/` dir
:language: c
Repeat the above pattern for each example in the current directory. That number
may be zero (0) for directories like `libs/` in which all examples are in directories
below that level. See directory structure above.
For paths outside the current directory, simply provide the path to the code example
relative to the `lvgl/examples/` directory. Example from
`lvgl/examples/widgets/scale/index.rst`:
.. code::
...
A round scale style simulating a compass
----------------------------------------
.. lv_example:: widgets/scale/lv_example_scale_12
:language: c
Axis ticks and labels with scrolling on a chart
-----------------------------------------------
.. lv_example:: widgets/chart/lv_example_chart_2 <-- path is outside scale/ dir
:language: c
.. note::
Starting the example code filename with `lv_example_` is not a requirement of the
this script, but does make it clear that it is an example, so this pattern should
be preserved for new and changed examples.
Custom Section Headings
-----------------------
If a section heading needs to be spelled differently than the capitalized name of the
parent directory, then an `index.rst` file in that directory may contain the desired
section-heading name in an ``.. example_heading`` pseudo-directive. Example from
`lvgl/examples/libs/index.rst`:
.. code::
.. example_heading: 3rd-Party Libraries
Directory Reordering
--------------------
There are cases where it is not appropriate to present the contents of a
set of subdirectories in alphabetical order. When this is the case, a
pseudo-directive in the `index.rst` file in the parent directory can be specified
to govern the sequence its subdirectories are processed. The example below
is from `lvgl/examples/widgets/index.rst`. It is provided in order to
cause the "Base Widget" (obj) directory to be processed first (and thus
included in the output first).
.. code::
.. dir_order:
obj
animimg
arc
arclabel
bar
button
buttonmatrix
etc.
.. note::
A warning is issued if either:
- a subdirectory is named that does not exist, or
- a subdirectory exists that is not in the list and not in the `avoid_dirs` list.
Making Warnings into Errors
***************************
If `make_warnings_into_errors()` was called, if there were any warnings
issued, after the output is completely generated, this script will exit
with a non-zero exit code. This can be done by client modules like this:
.. code::
import example_list
example_list.make_warnings_into_errors()
example_list.exec(intermediate_dir)
To turn it off:
.. code::
example_list.make_warnings_into_errors(False)
Debug Output
************
Enable debug output like this:
.. code::
example_list.DEBUG_MODE = True
Suppressing DEBUG_MODE is the default.
"""
import os
import sys
from io import TextIOWrapper
from announce import *
# -------------------------------------------------------------------------
# This is the order that LVGL documentation uses for the section heading
# levels. header_defs[0] is the highest and header_defs[5] is the lowest.
# If this order is not kept in the reST files Sphinx will complain, and
# have difficulty formatting the TOC correctly.
# -------------------------------------------------------------------------
TITLE = '='
CHAPTER = '*'
SECTION = '-'
SUBSECTION = '~'
SUBSUBSECTION = '^'
SUBSUBSUBSECTION = "'"
header_defs = [
TITLE,
CHAPTER,
SECTION,
SUBSECTION,
SUBSUBSECTION,
SUBSUBSUBSECTION,
]
LV_EXAMPLE_DIRECTIVE = '.. lv_example::'
EXAMPLE_HEADING_DIRECTIVE = '.. example_heading:'
DIR_ORDER_DIRECTIVE = '.. dir_order:'
DIR_SEP = os.sep
INDEX_FILENAME = 'index.rst'
MAKE_WARNINGS_INTO_ERRORS = False
DEBUG_MODE = False
THIS_FILE = os.path.basename(__file__)
_warning_issued = False
_top_level_heading_count = 0
avoid_dirs = [
os.path.join('examples', 'arduino'),
os.path.join('examples', 'assets'),
]
def make_warnings_into_errors(val: bool = True):
global MAKE_WARNINGS_INTO_ERRORS
MAKE_WARNINGS_INTO_ERRORS = val
def _default_section_heading(level: int, path: str, is_file: bool) -> str:
if is_file:
dir_path = os.path.dirname(path)
else:
dir_path = path
parent_dir = os.path.basename(dir_path)
# Compose default section heading based on capitalized words in `parent_dir`.
word_list = parent_dir.replace('_', ' ').replace('-', ' ').split(' ')
result = ''
for word in word_list:
result += ' ' + word.capitalize()
# Remove leading space.
if result:
result = result[1:]
return result
def _warn(msg: str):
global _warning_issued
if MAKE_WARNINGS_INTO_ERRORS:
warning_type = 'Error'
else:
warning_type = 'Warning'
if is_silent_mode():
print(f'{THIS_FILE}: ' + '\x1b[31m' + f'>>> {warning_type}: ' + msg + '\x1b[0m')
else:
announce_colored(THIS_FILE, 'red', f'>>> {warning_type}: ' + msg)
_warning_issued = True
def _in_avoid_dirs_list(dir_bep: str) -> bool:
result = False
for avoid_dir in avoid_dirs:
if avoid_dir in dir_bep:
result = True
break
return result
def _validate_sub_dirs(sub_dirs: list[str], index_rst_path: str) -> bool:
""" Validate sub-dirs that come from an `index.rst` `.. dir_order:` directive.
1. Check that that each one is an existing directory.
2. Check that there are none missing except those in `avoid_dirs`.
Issue warning if either fails and set `_warning_issued`.
If MAKE_WARNINGS_INTO_ERRORS, this will make script exit with an error
code at the end.
:param sub_dirs: List of sub-dirs to validate
:param index_rst_path: Path to index.rst file
:return: Whether `sub_dirs` is valid per 1 and 2 above
"""
result = True
# Check that each sub-dir is an existing directory.
for sub_dir in sub_dirs:
if not os.path.isdir(sub_dir):
result = False
_warn(f'Dir-order directive in {index_rst_path} contains dir [{sub_dir}] that does not exist.')
# We won't break here so that all such dirs can be listed.
# Check that there are none missing except those in `avoid_dirs`.
dir_path = os.path.dirname(index_rst_path)
actual_dirs = []
for dir_item in os.listdir(dir_path):
path_bep = os.path.join(dir_path, dir_item)
if os.path.isdir(path_bep):
actual_dirs.append(path_bep)
# Are there any missing that are not in `avoid_dirs` list?
# If so, issue warning about each directory missing.
for sub_dir in actual_dirs:
if sub_dir not in sub_dirs:
if not _in_avoid_dirs_list(sub_dir):
_warn(f'Dir-order directive in {index_rst_path} is missing dir [{sub_dir}].')
result = False
return result
def _emit_heading(level: int, hdg: str, f: TextIOWrapper):
"""
Emit reST heading using `header_defs`.
:param level: Directory depth below the top directory in tree. [0-5]
:param hdg: Heading text
:param f: Output file (examples.rst)
:return:
"""
assert 0 <= level < len(header_defs), "level out of range"
global _top_level_heading_count
underline = header_defs[level] * len(hdg)
announce(__file__, f'Section heading [{hdg}] at level [{level}].')
if level == 0:
_top_level_heading_count += 1
if _top_level_heading_count > 1:
f.write('\n\n\n') # 3 extra lines above (doc) root titles, except 1st
f.write(underline)
f.write('\n')
elif level == 1:
f.write('\n\n') # 2 extra lines above chapters
elif level == 2:
f.write('\n') # 1 extra line above sections
f.write(hdg)
f.write('\n')
f.write(underline)
f.write('\n\n')
def _generate_output_from_dir(level: int,
root_len: int,
file_or_dir: str,
is_file: bool,
orig_dir_list: list[str],
f: TextIOWrapper) -> list[str]:
""" Output to `f` based on contents of `file_or_dir`.
:param level: Directory depth below the top directory in tree. [0-4]
:param root_len: Length of root path -- is deleted from paths so that
paths are relative to the `lvgl/examples/` dir.
:param file_or_dir: Path to "thing" being processed.
:param is_file: True if `file_or_dir` is an `index.rst` file.
:param orig_dir_list: List of sub-dirs below dir being processed.
Will be returned from this function if a
dir-order directive is NOT found in index file.
:param f: Output file (examples.rst)
:return: `orig_dir_list` or `dir_order_override` if a
dir-order directive is found in index file.
"""
dir_order_override = []
result_dir_list = orig_dir_list
# It is an error to proceed with `level` out of range. Clamping it to be in
# range is also an error because it would cause the output to be corrupted with
# an invalid section-heading underscore, which would generate an error later.
if 0 <= level and level + 1 < len(header_defs):
section_heading = _default_section_heading(level, file_or_dir, is_file)
example_tuples = []
relative_dir = ''
if is_file:
announce(__file__, f'Processing file [{file_or_dir}]...')
# We are processing an index.rst file.
with open(file_or_dir, 'r', encoding='utf-8') as fidx:
# It is important that this is NOT fidx.readlines() because
# it leaves blank lines containing '\n' instead of ''.
lines = fidx.read().split('\n')
example_title = ''
prev_line = ''
dir_path = os.path.dirname(file_or_dir)
in_dir_order_directive = False
# Accumulate data from `index.rst`. This needs to be done
# first in case it overrides the default section heading.
for line in lines:
if in_dir_order_directive:
leading_non_blank = (len(line) > 0) and not (line[0] == ' ' or line[0] == '\t')
if leading_non_blank:
# Leading non-blank character ends dir-order directive.
in_dir_order_directive = False
else:
# Still in dir-order directive.
stripped_line = line.strip()
if stripped_line:
dir_order_override.append(os.path.join(dir_path, stripped_line))
continue
stripped_line = line.strip()
if not stripped_line:
continue # Skip blank line.
elif stripped_line.startswith(EXAMPLE_HEADING_DIRECTIVE):
new_heading = stripped_line.replace(EXAMPLE_HEADING_DIRECTIVE, '').strip()
announce(__file__, f'Default section heading [{section_heading}] replaced with [{new_heading}]...')
section_heading = new_heading
elif stripped_line.startswith('---'):
example_title = prev_line
announce(__file__, f'Found example [{example_title}]...')
elif stripped_line.startswith(LV_EXAMPLE_DIRECTIVE):
rel_path_from_examples_dir = stripped_line.replace(LV_EXAMPLE_DIRECTIVE, '').strip()
announce(__file__, f' [{rel_path_from_examples_dir}]')
example_tuples.append( (example_title, rel_path_from_examples_dir) )
elif not in_dir_order_directive and stripped_line.startswith(DIR_ORDER_DIRECTIVE):
in_dir_order_directive = True
announce(__file__, f'Found DIR-ORDER directive.')
prev_line = stripped_line
# Output section heading. This occurs even when we have descended into an
# empty directory with example sub-dirs below it.
_emit_heading(level, section_heading, f)
# Output examples, if any. Will be empty when we are in an empty directory
# with example sub-dirs below it.
for example_tuple in example_tuples:
example_title = example_tuple[0]
rel_path_from_examples_dir = example_tuple[1]
example_hdg_underline = header_defs[level + 1] * len(example_title)
announce(__file__, f'Writing example [{rel_path_from_examples_dir}]...')
_emit_heading(level + 1, example_title, f)
f.write(LV_EXAMPLE_DIRECTIVE + ' ' + rel_path_from_examples_dir)
f.write('\n\n')
if dir_order_override:
_validate_sub_dirs(dir_order_override, file_or_dir)
result_dir_list = dir_order_override
return result_dir_list
def process_dir_recursively(level: int, root_len: int, dir_bep: str, f: TextIOWrapper):
""" Process dir `dir_bep` recursively, avoiding sub-dirs in `avoid_dirs`.
:param level: Directory depth below the top directory in tree.
:param root_len: Length of root path (gets removed from full path)
:param dir_bep: Directory *being processed*
:param f: Output file (examples.rst)
"""
announce(__file__, f'Processing dir [{dir_bep}]...')
sub_dirs = []
idx_files = []
if not os.path.isdir(dir_bep):
_warn(f'process_dir_recursively: `dir_bep` [{dir_bep}] does not exist.')
return
# For each "thing" found in `dir_bep`, build lists: sub_dirs and idx_files.
for dir_item in os.listdir(dir_bep):
path_bep = os.path.join(dir_bep, dir_item)
if os.path.isdir(path_bep):
sub_dirs.append(path_bep)
elif path_bep.endswith(INDEX_FILENAME):
idx_files.append(path_bep)
if idx_files:
sub_dirs = _generate_output_from_dir(level, root_len, idx_files[0], True, sub_dirs, f)
# `sub_dirs` can be replaced if `index.rst` contains a dir-order directive.
else:
_generate_output_from_dir(level, root_len, dir_bep, False, sub_dirs, f)
# Now recursively process sub_dirs.
for subdir in sub_dirs:
if not _in_avoid_dirs_list(subdir):
process_dir_recursively(level + 1, root_len, subdir, f)
def exec(intermediate_dir):
announce_set_silent_mode(not DEBUG_MODE)
output_path = os.path.join(intermediate_dir, 'examples.rst')
input_paths = [
os.path.join('..', 'examples'),
# os.path.join('..', 'demos')
]
with open(output_path, 'w', encoding='utf-8') as f:
f.write('.. _examples:\n')
f.write('\n')
# Recursively walk the directories in `input_paths` array for
# ``index.rst`` files.
for root_path in input_paths:
root_len = len(root_path) + 1
process_dir_recursively(0, root_len, root_path, f)
if MAKE_WARNINGS_INTO_ERRORS and _warning_issued:
exit(1)
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])