feat(docs): migrate from .md to .rst (#4129)

docs/_ext/lv_example.py

@@ -2,16 +2,14 @@ import os
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
-from docutils.parsers.rst.directives.images import Image
-from sphinx.directives.code import LiteralInclude
+# 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 = 1
     option_spec = {
@@ -19,8 +17,13 @@ class LvExample(Directive):
         'language': directives.unchanged,
         'description': directives.unchanged
     }
+
     def get_example_code_path(self, example_path, language):
-        return os.path.abspath("../examples/" + example_path + "." + language)
+        base_path = os.path.dirname(__file__)
+        examples_path = os.path.abspath(os.path.join(base_path, '..', 'examples'))
+        example_path = os.path.join(examples_path, example_path + '.' + language)
+        return example_path
+
     def human_language_name(self, language):
         if language == 'py':
             return 'MicroPython'
@@ -28,18 +31,23 @@ class LvExample(Directive):
             return 'C'
         else:
             return language
+
     def github_path(self, example_path, language):
         env = self.state.document.settings.env
         return f"https://github.com/lvgl/lvgl/blob/{env.config.repo_commit_hash}/examples/{example_path}.{language}"
+
     def embed_code(self, example_file, example_path, language, buttons={}):
         toggle = nodes.container('', literal_block=False, classes=['toggle'])
         header = nodes.container('', literal_block=False, classes=['header'])
         toggle.append(header)
+
         try:
-            with open(example_file) as f:
-                contents = f.read()
+            with open(example_file, 'rb') as f:
+                contents = f.read().decode('utf-8')
         except FileNotFoundError:
+            print('File Not Found', example_file)
             contents = 'Error encountered while trying to open ' + example_file
+
         literal_list = nodes.literal_block(contents, contents)
         literal_list['language'] = language
         toggle.append(literal_list)
@@ -48,6 +56,7 @@ class LvExample(Directive):
             paragraph_node.append(nodes.raw(text=f"<a class='lv-example-link-button' onclick=\"event.stopPropagation();\" href='{url}'>{text}</a>", format='html'))
         header.append(paragraph_node)
         return toggle
+
     def run(self):
         example_path = self.arguments[0]
         example_name = os.path.split(example_path)[1]
@@ -61,15 +70,22 @@ class LvExample(Directive):
         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', buttons={
-            '<i class="fa fa-github"></i>&nbsp;GitHub': self.github_path(example_path, 'c')
-        })
-        py_code = self.embed_code(py_path, example_path, 'py', buttons={
-            '<i class="fa fa-github"></i>&nbsp;GitHub': self.github_path(example_path, 'py'),
-            '<i class="fa fa-play"></i>&nbsp;Simulator': f"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"
-        })
+        if os.path.exists(c_path):
+            c_code = self.embed_code(c_path, example_path, 'c', buttons={
+                '<i class="fa fa-github"></i>&nbsp;View on GitHub': self.github_path(example_path, 'c')
+            })
+        else:
+            c_code = None
 
-        if not 'c' in excluded_languages:
+        if os.path.exists(py_path):
+            py_code = self.embed_code(py_path, example_path, 'py', buttons={
+                '<i class="fa fa-github"></i>&nbsp;View on GitHub': self.github_path(example_path, 'py'),
+                '<i class="fa fa-play"></i>&nbsp;MicroPython Simulator': f"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"
+            })
+        else:
+            py_code = None
+
+        if 'c' not in excluded_languages:
             if env.app.tags.has('html'):
                 iframe_html = f"<div class='lv-example' data-real-src='/{env.config.version}/_static/built_lv_examples/index.html?example={example_name}&w=320&h=240'></div>"
 
@@ -77,9 +93,9 @@ class LvExample(Directive):
         layout_node = nodes.raw(text=f"<div class='lv-example-container'>{iframe_html}{description_html}</div>", format='html')
 
         node_list.append(layout_node)
-        if not 'c' in excluded_languages:
+        if 'c' not in excluded_languages and c_code is not None:
             node_list.append(c_code)
-        if not 'py' in excluded_languages:
+        if 'py' not in excluded_languages and py_code is not None:
             node_list.append(py_code)
 
         trailing_node = nodes.raw(text=f"<hr/>", format='html')
@@ -87,6 +103,7 @@ class LvExample(Directive):
 
         return node_list
 
+
 def setup(app):
     app.add_directive("lv_example", LvExample)
     app.add_config_value("repo_commit_hash", "", "env")