docs(examples) add MicroPython examples

2021-06-11 16:45:03 -04:00
parent 1a62f7a619
commit 6f37c4fc56
40 changed files with 63 additions and 248 deletions
--- a/docs/_ext/lv_example.py
+++ b/docs/_ext/lv_example.py
@@ -1,30 +1,37 @@
 import os

 from docutils import nodes
-from docutils.parsers.rst import Directive
+from docutils.parsers.rst import Directive, directives
 from docutils.parsers.rst.directives.images import Image
 from sphinx.directives.code import LiteralInclude


+def excluded_list(argument):
+    return argument.split(',')
+
+
+
+
 class LvExample(Directive):
-    required_arguments = 3
-    def run(self):
-        example_path = self.arguments[0]
-        example_name = os.path.split(example_path)[1]
-        language = self.arguments[2]
-        node_list = []
-
-        env = self.state.document.settings.env
-
-        if self.arguments[2] == 'py':
-            paragraph_node = nodes.raw(text=f"Click to try in the simulator!<br/><a target='_blank' href='https://sim.lvgl.io/v7/micropython/ports/javascript/bundle_out/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lv_examples/{env.config.example_commit_hash}/src/header.py&script=https://raw.githubusercontent.com/lvgl/lv_examples/{env.config.built_example_commit_hash}/{example_name}/{example_name}.py'><img alt='{example_name}' src='https://raw.githubusercontent.com/lvgl/lv_examples/{env.config.built_example_commit_hash}/{example_name}/{example_name}.png'/></a>", format='html')
+    required_arguments = 1
+    option_spec = {
+        'excluded_languages': excluded_list,
+        'language': directives.unchanged
+    }
+    def get_example_code_path(self, example_path, language):
+        return os.path.abspath("../examples/" + example_path + "." + language)
+    def human_language_name(self, language):
+        if language == 'py':
+            return 'MicroPython'
+        elif language == 'c':
+            return 'C'
        else:
-            paragraph_node = nodes.raw(text=f"<iframe class='lv-example' src='/{env.config.version}/_static/built_lv_examples?example={example_name}&w=320&h=240'></iframe>", format='html')
+            return language
+    def embed_code(self, example_file, example_path, language):
+        env = self.state.document.settings.env
        toggle = nodes.container('', literal_block=False, classes=['toggle'])
        header = nodes.container('', literal_block=False, classes=['header'])
        toggle.append(header)
-        example_file = os.path.abspath("../examples/" + example_path + "." + self.arguments[2])
-
        try:
            with open(example_file) as f:
                contents = f.read()
@@ -33,10 +40,35 @@ class LvExample(Directive):
        literal_list = nodes.literal_block(contents, contents)
        literal_list['language'] = language
        toggle.append(literal_list)
-        header.append(nodes.raw(text=f"<p>code &nbsp; <a class='fa fa-github' href='https://github.com/lvgl/lvgl/blob/{env.config.repo_commit_hash}/examples/{example_path}.{language}'>&nbsp; view on GitHub</a></p>", format='html'))
+        header.append(nodes.raw(text=f"<p>{self.human_language_name(language)} code &nbsp; <a onclick=\"event.stopPropagation();\" class='fa fa-github' href='https://github.com/lvgl/lvgl/blob/{env.config.repo_commit_hash}/examples/{example_path}.{language}'>&nbsp; view on GitHub</a></p>", format='html'))
+        return toggle
+    def run(self):
+        example_path = self.arguments[0]
+        example_name = os.path.split(example_path)[1]
+        excluded_languages = self.options.get('excluded_languages', [])
+        node_list = []
+
+        env = self.state.document.settings.env
+
+        iframe_node = nodes.raw(text=f"<iframe class='lv-example' src='/{env.config.version}/_static/built_lv_examples?example={example_name}&w=320&h=240'></iframe>", format='html')
+        micropython_node = nodes.raw(text=f"<a style='display: inline-block; margin-bottom: 1rem;' target='_blank' href='https://sim.lvgl.io/v{env.config.version}/micropython/ports/javascript/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lvgl/{env.config.repo_commit_hash}/examples/header.py&script=https://raw.githubusercontent.com/lvgl/lvgl/{env.config.repo_commit_hash}/examples/{example_path}.py'>Click to try in the MicroPython simulator!</a>", format='html')
+
+        c_path = self.get_example_code_path(example_path, 'c')
+        py_path = self.get_example_code_path(example_path, 'py')
+
+        c_code = self.embed_code(c_path, example_path, 'c')
+        py_code = self.embed_code(py_path, example_path, 'py')
+
+        if not 'c' in excluded_languages:   
            if env.app.tags.has('html'):
-            node_list.append(paragraph_node)
-        node_list.append(toggle)
+                node_list.append(iframe_node)
+        if not 'py' in excluded_languages:
+            node_list.append(micropython_node)
+        if not 'c' in excluded_languages:
+            node_list.append(c_code)
+        if not 'py' in excluded_languages:
+            node_list.append(py_code)
+
        return node_list

 def setup(app):
--- a/examples/anim/index.rst
+++ b/examples/anim/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Start animation on an event 
 """"""""""""""""""""""""""""
@@ -13,7 +11,3 @@ Playback animation
  :language: c

  
-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/event/index.rst
+++ b/examples/event/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Button click event
 """""""""""""""""""
@@ -19,7 +17,3 @@ Event bubbling
  :language: c

  
-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/get_started/index.rst
+++ b/examples/get_started/index.rst
@@ -1,5 +1,3 @@
-C
-^

 A button with a label and react on click event
 """""""""""""""""""""""""""""""""""""""""""""""""
@@ -18,7 +16,3 @@ Create a slider and write its value on a label
  :language: c

  
-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/header.py
+++ b/examples/header.py
@@ -1,3 +1,14 @@
 #!/opt/bin/lv_micropython -i
+
 import lvgl as lv
+try:
+    import sys
+except ImportError:
+    import usys as sys
+
+# JS requires a special import
+if sys.platform == 'javascript':
+  import imp
+  sys.path.append('https://raw.githubusercontent.com/lvgl/lv_binding_micropython/4c04dba836a5affcf86cef107b538e45278117ae/lib')
+
 import display_driver
--- a/examples/layouts/flex/index.rst
+++ b/examples/layouts/flex/index.rst
@@ -1,5 +1,3 @@
-C
-^
 A simple row and a column layout with flexbox
 """""""""""""""""""""""""""""""""""""""""""""""

@@ -37,7 +35,3 @@ RTL base direction changes order of the items
  :language: c
  

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/layouts/grid/index.rst
+++ b/examples/layouts/grid/index.rst
@@ -1,5 +1,3 @@
-C
-^
 A simple grid
 """""""""""""""

@@ -37,7 +35,3 @@ Demonstrate RTL direction on grid
  :language: c
  

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/scroll/index.rst
+++ b/examples/scroll/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Nested scrolling 
 """"""""""""""""
@@ -33,7 +31,3 @@ Translate on scroll
  :language: c
  
  
-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/styles/index.rst
+++ b/examples/styles/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Size styles
 """""""""""""""""""
@@ -91,7 +89,3 @@ Extending the current theme
  :language: c
  
  
-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/arc/index.rst
+++ b/examples/widgets/arc/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Arc 
 """"""""""""""""
@@ -13,7 +11,3 @@ Loader with Arc
 .. lv_example:: widgets/arc/lv_example_arc_2
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/bar/index.rst
+++ b/examples/widgets/bar/index.rst
@@ -1,5 +1,3 @@
-C
-^
 Simple Bar 
 """"""""""""""""

@@ -36,7 +34,3 @@ Custom drawr to show the current value
 .. lv_example:: widgets/bar/lv_example_bar_6
  :language: c
  
-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/btn/index.rst
+++ b/examples/widgets/btn/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Buttons 
 """"""""""""""""
@@ -20,7 +18,3 @@ Gummy button
 .. lv_example:: widgets/btn/lv_example_btn_3
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/btnmatrix/index.rst
+++ b/examples/widgets/btnmatrix/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Button matrix 
 """"""""""""""""""""""
@@ -22,7 +20,3 @@ Pagination
  :language: c


-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/calendar/index.rst
+++ b/examples/widgets/calendar/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Calendar with header 
 """"""""""""""""""""""
@@ -7,7 +5,3 @@ Calendar with header
 .. lv_example:: widgets/calendar/lv_example_calendar_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/canvas/index.rst
+++ b/examples/widgets/canvas/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Drawing on the Canvas and rotate 
 """"""""""""""""""""""""""""""""""
@@ -13,7 +11,3 @@ Transparent Canvas with chroma keying
 .. lv_example:: widgets/canvas/lv_example_canvas_2
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/chart/index.rst
+++ b/examples/widgets/chart/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Line Chart 
 """"""""""
@@ -45,7 +43,3 @@ Scatter chart
  :language: c


-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/checkbox/index.rst
+++ b/examples/widgets/checkbox/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Checkboxes
 """""""""""""""""
@@ -7,7 +5,3 @@ Simple Checkboxes
 .. lv_example:: widgets/checkbox/lv_example_checkbox_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/colorwheel/index.rst
+++ b/examples/widgets/colorwheel/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Colorwheel
 """""""""""""""""
@@ -7,7 +5,3 @@ Simple Colorwheel
 .. lv_example:: widgets/colorwheel/lv_example_colorwheel_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/dropdown/index.rst
+++ b/examples/widgets/dropdown/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Drop down list
 """"""""""""""""""""""
@@ -20,7 +18,3 @@ Menu
 .. lv_example:: widgets/dropdown/lv_example_dropdown_3
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/img/index.rst
+++ b/examples/widgets/img/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Image from variable and symbol 
 """""""""""""""""""""""""""""""
@@ -28,7 +26,3 @@ Image offset and styling
  :language: c


-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/imgbtn/index.rst
+++ b/examples/widgets/imgbtn/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Image button 
 """""""""""""""""""
@@ -7,7 +5,3 @@ Simple Image button
 .. lv_example:: widgets/imgbtn/lv_example_imgbtn_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/keyboard/index.rst
+++ b/examples/widgets/keyboard/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Keyboard with text area 
 """""""""""""""""""""""
@@ -7,10 +5,3 @@ Keyboard with text area
 .. lv_example:: _widgets/keyboard/lv_example_keyboard_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-Keyboard with text area
-"""""""""""""""""""""""
-
-No examples yet.
--- a/examples/widgets/label/index.rst
+++ b/examples/widgets/label/index.rst
@@ -1,5 +1,3 @@
-C
-^
  
 Line wrap, recoloring and scrolling 
 """""""""""""""""""""""""""""""""""
@@ -19,7 +17,3 @@ Show LTR, RTL and Chinese texts
 .. lv_example:: widgets/label/lv_example_label_3
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/led/index.rst
+++ b/examples/widgets/led/index.rst
@@ -1,5 +1,3 @@
-C
-^

 LED with custom style
 """""""""""""""""""""
@@ -7,7 +5,3 @@ LED with custom style
 .. lv_example:: widgets/led/lv_example_led_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/line/index.rst
+++ b/examples/widgets/line/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Line 
 """"""""""""""""
@@ -7,7 +5,3 @@ Simple Line
 .. lv_example:: widgets/line/lv_example_line_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/list/index.rst
+++ b/examples/widgets/list/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple List 
 """"""""""""""""
@@ -7,7 +5,3 @@ Simple List
 .. lv_example:: widgets/list/lv_example_list_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/meter/index.rst
+++ b/examples/widgets/meter/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple meter
 """""""""""""""""""""""
@@ -28,7 +26,3 @@ Pie chart
 .. lv_example:: widgets/meter/lv_example_meter_4
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/msgbox/index.rst
+++ b/examples/widgets/msgbox/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Message box 
 """""""""""""""""""
@@ -8,7 +6,3 @@ Simple Message box
  :language: c


-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/obj/index.rst
+++ b/examples/widgets/obj/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Base objects with custom styles 
 """"""""""""""""""""""""""""""""
@@ -13,7 +11,3 @@ Make an object draggable
 .. lv_example:: widgets/obj/lv_example_obj_2
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/roller/index.rst
+++ b/examples/widgets/roller/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Roller 
 """"""""""""""""
@@ -19,7 +17,3 @@ add fade mask to roller
 .. lv_example:: widgets/roller/lv_example_roller_3
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/slider/index.rst
+++ b/examples/widgets/slider/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Slider
 """""""""""""""""""""""""
@@ -20,7 +18,3 @@ Slider with extended drawer
  :language: c
  

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/span/index.rst
+++ b/examples/widgets/span/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Span with custom styles
 """"""""""""""""""""""""
@@ -7,7 +5,3 @@ Span with custom styles
 .. lv_example:: widgets/span/lv_example_span_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/spinbox/index.rst
+++ b/examples/widgets/spinbox/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Spinbox 
 """""""""""""""""""""""
@@ -7,7 +5,3 @@ Simple Spinbox
 .. lv_example:: widgets/spinbox/lv_example_spinbox_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/spinner/index.rst
+++ b/examples/widgets/spinner/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple spinner 
 """"""""""""""""""""""""""""
@@ -7,5 +5,3 @@ Simple spinner
 .. lv_example:: widgets/spinner/lv_example_spinner_1
  :language: c

-MicroPython
-^^^^^^^^^^^
--- a/examples/widgets/switch/index.rst
+++ b/examples/widgets/switch/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Switch 
 """""""""""""""""""""""
@@ -7,7 +5,3 @@ Simple Switch
 .. lv_example:: widgets/switch/lv_example_switch_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/table/index.rst
+++ b/examples/widgets/table/index.rst
@@ -1,5 +1,4 @@
-C
-^
+

 Simple table 
 """""""""""""""""""""""
@@ -13,7 +12,3 @@ Lightweighted list from table
 .. lv_example:: widgets/table/lv_example_table_2
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/tabview/index.rst
+++ b/examples/widgets/tabview/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Tabview 
 """""""""""""""""""""""
@@ -14,7 +12,3 @@ Tabs on the left, styling and no scrolling
  :language: c


-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/textarea/index.rst
+++ b/examples/widgets/textarea/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple Text area
 """""""""""""""""""""""
@@ -20,7 +18,3 @@ Text auto-formatting
 .. lv_example:: widgets/textarea/lv_example_textarea_3
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/tileview/index.rst
+++ b/examples/widgets/tileview/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Tileview with content 
 """""""""""""""""""""""""""
@@ -7,7 +5,3 @@ Tileview with content
 .. lv_example:: widgets/tileview/lv_example_tileview_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.
--- a/examples/widgets/win/index.rst
+++ b/examples/widgets/win/index.rst
@@ -1,5 +1,3 @@
-C
-^

 Simple window 
 """""""""""""""
@@ -7,7 +5,3 @@ Simple window
 .. lv_example:: widgets/win/lv_example_win_1
  :language: c

-MicroPython
-^^^^^^^^^^^
-
-No examples yet.