lvgl/examples/README.md

Examples Directory Requirements

lvgl/examples/
    index.rst        (directory-order 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.

index.rst Requirements

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 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:

...

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 example_list.py 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:

.. example_heading: 3rd-Party Libraries

Optional 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).

.. 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.