feat(docs) improvements to examples

* examples are now loaded only when they are visible on your screen * stylistic improvements * support for a description
lvgl · Jun 18, 2021 · 4b8c73a · 4b8c73a
1 parent 7c1eb00
commit 4b8c73a
Showing 7 changed files with 92 additions and 380 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,6 +8,7 @@ scripts/cppcheck_res.txt
 scripts/built_in_font/lv_font_*
 docs/doxygen_html
 docs/xml
+docs/examples.md
 docs/out_latex
 docs/_static/built_lv_examples
 docs/LVGL.pdf

diff --git a/docs/_ext/lv_example.py b/docs/_ext/lv_example.py
@@ -16,7 +16,8 @@ class LvExample(Directive):
     required_arguments = 1
     option_spec = {
         'excluded_languages': excluded_list,
-        'language': directives.unchanged
+        'language': directives.unchanged,
+        'description': directives.unchanged
     }
     def get_example_code_path(self, example_path, language):
         return os.path.abspath("../examples/" + example_path + "." + language)
@@ -27,8 +28,10 @@ def human_language_name(self, language):
             return 'C'
         else:
             return language
-    def embed_code(self, example_file, example_path, 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)
@@ -40,7 +43,10 @@ def embed_code(self, example_file, example_path, language):
         literal_list = nodes.literal_block(contents, contents)
         literal_list['language'] = language
         toggle.append(literal_list)
-        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'))
+        paragraph_node = nodes.raw(text=f"<p>{self.human_language_name(language)} code &nbsp;</p>", format='html')
+        for text, url in buttons.items():
+            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]
@@ -50,20 +56,27 @@ def run(self):
 
         env = self.state.document.settings.env
 
-        iframe_node = nodes.raw(text=f"<iframe loading='lazy' 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')
-
+        iframe_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')
+        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 not 'c' in excluded_languages:   
             if env.app.tags.has('html'):
-                node_list.append(iframe_node)
-        if not 'py' in excluded_languages:
-            node_list.append(micropython_node)
+                iframe_html = f"<div class='lv-example' data-real-src='/{env.config.version}/_static/built_lv_examples?example={example_name}&w=320&h=240'></div>"
+
+        description_html = f"<div class='lv-example-description'>{self.options.get('description', '')}</div>"
+        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:
             node_list.append(c_code)
         if not 'py' in excluded_languages:

diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -19,7 +19,7 @@ span.pre:first-child
 
 code.sig-name
 {
-  //margin-left:8px;
+  /*margin-left:8px;*/
 }
 
 .toggle .header {
@@ -64,11 +64,42 @@ code.sig-name
   transform: translate(0, -10px);
 }
 
-.lv-example {
+.lv-example, .lv-example > iframe {
   border: none;
   outline: none;
   padding: none;
   display: block;
   width: 320px;
   height: 240px;
+  flex: none;
+  position: relative;
 }
+.lv-example > iframe {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+
+.lv-example-container {
+    display: flex;
+}
+.lv-example-description {
+    flex: 1 1 auto;
+}
+
+.lv-example-link-button {
+    display: inline-block;
+    padding: 4px 8px;
+    border-radius: 4px;
+    background-color: #2980b9;
+    color: white;
+    margin: 0 4px;
+}
+.lv-example-link-button:hover {
+    color: white;
+    filter: brightness(120%);
+}
+
+.lv-example-link-button:visited {
+    color: white;
+}
diff --git a/docs/_templates/page.html b/docs/_templates/page.html
@@ -51,5 +51,32 @@
     });
 
 })
+document.addEventListener('DOMContentLoaded', (event) => {
+    function onIntersection(entries) {
+        entries.forEach(entry => {
+            let currentlyLoaded = entry.target.getAttribute("data-is-loaded") == "true";
+            let shouldBeLoaded = entry.intersectionRatio > 0;
+            if(currentlyLoaded != shouldBeLoaded) {
+                entry.target.setAttribute("data-is-loaded", shouldBeLoaded);
+                if(shouldBeLoaded) {
+                    let iframe = document.createElement("iframe");
+                    iframe.src = entry.target.getAttribute("data-real-src");
+                    entry.target.appendChild(iframe);
+                } else {
+                    let iframe = entry.target.querySelector("iframe");
+                    iframe.parentNode.removeChild(iframe);
+                }
+            }
+        });
+    }
+    const config = {
+        rootMargin: '50px 0px',
+        threshold: 0.01
+    };
+    let observer = new IntersectionObserver(onIntersection, config);
+    document.querySelectorAll(".lv-example").forEach(iframe => {
+        observer.observe(iframe);
+    });
+});
 </script>
 {% endblock %}
diff --git a/docs/example_list.py b/docs/example_list.py
@@ -1,5 +1,7 @@
+#!/usr/bin/env python3
 import os
-
+
+
 def process_index_rst(path):
 #  print(path)
   with open(path) as fp:
@@ -73,10 +75,11 @@ def process_index_rst(path):
 def print_item(path, lvl, d, fout):
   for k in d:
     v = d[k]
-    b = os.path.basename(k)
     if k.startswith(path + "/lv_example_"):
      fout.write("#"*lvl + " " + v + "\n")
-     fout.write('<iframe loading="lazy" class="lv-example" src="_static/built_lv_examples?example=' + b +'&amp;w=320&amp;h=240"></iframe>\n')
+     fout.write('```eval_rst\n')
+     fout.write(f".. lv_example:: {k}\n")
+     fout.write('```\n')
      fout.write("\n")
 
 def exec():