From 4b8c73a5770657ab55bbe825f7887e28c55a8a4a Mon Sep 17 00:00:00 2001 From: Themba Dube Date: Fri, 18 Jun 2021 12:25:49 -0400 Subject: [PATCH] feat(docs) improvements to examples * examples are now loaded only when they are visible on your screen * stylistic improvements * support for a description --- .gitignore | 1 + docs/_ext/lv_example.py | 35 +++- docs/_static/css/custom.css | 35 +++- docs/_templates/page.html | 27 +++ docs/example_list.py | 9 +- docs/examples.md | 364 --------------------------------- examples/widgets/arc/index.rst | 1 + 7 files changed, 92 insertions(+), 380 deletions(-) delete mode 100644 docs/examples.md diff --git a/.gitignore b/.gitignore index 0286e4ad6..7ea1e3412 100644 --- 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 index 4679d76d8..08fcf9f52 100644 --- 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 @@ class LvExample(Directive): 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 @@ class LvExample(Directive): literal_list = nodes.literal_block(contents, contents) literal_list['language'] = language toggle.append(literal_list) - header.append(nodes.raw(text=f"

{self.human_language_name(language)} code     view on GitHub

", format='html')) + paragraph_node = nodes.raw(text=f"

{self.human_language_name(language)} code  

", format='html') + for text, url in buttons.items(): + paragraph_node.append(nodes.raw(text=f"{text}", format='html')) + header.append(paragraph_node) return toggle def run(self): example_path = self.arguments[0] @@ -50,20 +56,27 @@ class LvExample(Directive): env = self.state.document.settings.env - iframe_node = nodes.raw(text=f"", format='html') - micropython_node = nodes.raw(text=f"Click to try in the MicroPython simulator!", 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={ + ' GitHub': self.github_path(example_path, 'c') + }) + py_code = self.embed_code(py_path, example_path, 'py', buttons={ + ' GitHub': self.github_path(example_path, 'py'), + ' 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"
" + + description_html = f"
{self.options.get('description', '')}
" + layout_node = nodes.raw(text=f"
{iframe_html}{description_html}
", 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 index a5e2c2532..a6f9c406b 100644 --- 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; +} \ No newline at end of file diff --git a/docs/_templates/page.html b/docs/_templates/page.html index 9ceaae358..f29c63d4d 100644 --- a/docs/_templates/page.html +++ b/docs/_templates/page.html @@ -51,5 +51,32 @@ document.addEventListener('DOMContentLoaded', (event) => { }); }) +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); + }); +}); {% endblock %} diff --git a/docs/example_list.py b/docs/example_list.py index f4f9e325b..999d9d138 100755 --- 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 @@ layouts = { 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('\n') + fout.write('```eval_rst\n') + fout.write(f".. lv_example:: {k}\n") + fout.write('```\n') fout.write("\n") def exec(): diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 1a2c540e2..000000000 --- a/docs/examples.md +++ /dev/null @@ -1,364 +0,0 @@ -```eval_rst -.. include:: /header.rst -:github_url: |github_link_base|/examples.md -``` - -# Examples -## Get started -### A button with a label and react on click event - - -### Create styles from scratch for buttons - - -### Create a slider and write its value on a label - - -## Styles -### Size styles - - -### Background styles - - -### Border styles - - -### Outline styles - - -### Shadow styles - - -### Image styles - - -### Text styles - - -### Line styles - - -### Transition - - -### Using multiple styles - - -### Local styles - - -### Add styles to parts and states - - -### Extending the current theme - - -## Animations -### Start animation on an event - - -### Playback animation - - -## Events -### Button click event - - -### Handle multiple events - - -### Event bubbling - - -## Layouts -### Flex -#### A simple row and a column layout with flexbox - - -#### Arrange items in rows with wrap and even spacing - - -#### Demonstrate flex grow - - -#### Demonstrate flex grow. - - -#### Demonstrate column and row gap style properties - - -#### RTL base direction changes order of the items - - -### Grid -#### A simple grid - - -#### Demonstrate cell placement and span - - -#### Demonstrate grid's "free unit" - - -#### Demonstrate track placement - - -#### Demonstrate column and row gap - - -#### Demonstrate RTL direction on grid - - -## Scrolling -### Nested scrolling - - -### Snapping - - -### Floating button - - -### Styling the scrollbars - - -### Right to left scrolling - - -### Translate on scroll - - -## Widgets -### Base object -#### Base objects with custom styles - - -#### Make an object draggable - - -### Arc -#### Simple Arc - - -#### Loader with Arc - - -### Bar -#### Simple Bar - - -#### Styling a bar - - -#### Temperature meter - - -#### Stripe pattern and range value - - -#### Bar with RTL and RTL base direction - - -#### Custom drawr to show the current value - - -### Button -#### Simple Buttons - - -#### Styling buttons - - -#### Gummy button - - -### Button matrix -#### Simple Button matrix - - -#### Custom buttons - - -#### Pagination - - -### Calendar -#### Calendar with header - - -### Canvas -#### Drawing on the Canvas and rotate - - -#### Transparent Canvas with chroma keying - - -### Chart -#### Line Chart - - -#### Faded area line chart with custom division lines - - -#### Axis ticks and labels with scrolling - - -#### Show the value of the pressed points - - -#### Display 1000 data points with zooming and scrolling - - -#### Show cursor on the clicked point - - -#### Scatter chart - - -### Checkbox -#### Simple Checkboxes - - -### Colorwheel -#### Simple Colorwheel - - -### Dropdown -#### Simple Drop down list - - -#### Drop down in four directions - - -#### Menu - - -### Image -#### Image from variable and symbol - - -#### Image recoloring - - -#### Rotate and zoom - - -#### Image offset and styling - - -### Image button -#### Simple Image button - - -### Keyboard -#### Keyboard with text area - - -### Label -#### Line wrap, recoloring and scrolling - - -#### Text shadow - - -#### Show LTR, RTL and Chinese texts - - -### LED -#### LED with custom style - - -### Line -#### Simple Line - - -### List -#### Simple List - - -### Meter -#### Simple meter - - -#### A meter with multiple arcs - - -#### A clock from a meter - - -#### Pie chart - - -### Message box -#### Simple Message box - - -### Roller -#### Simple Roller - - -#### Styling the roller - - -#### add fade mask to roller - - -### Slider -#### Simple Slider - - -#### Slider with custom style - - -#### Slider with extended drawer - - -### Span -#### Span with custom styles - - -### Spinbox -#### Simple Spinbox - - -### Spinner -#### Simple spinner - - -### Switch -#### Simple Switch - - -### Table -#### Simple table - - -#### Lightweighted list from table - - -### Tabview -#### Simple Tabview - - -#### Tabs on the left, styling and no scrolling - - -### Textarea -#### Simple Text area - - -#### Text area with password field - - -#### Text auto-formatting - - -### Tabview -#### Tileview with content - - -### Window -#### Simple window - - diff --git a/examples/widgets/arc/index.rst b/examples/widgets/arc/index.rst index 7c529f990..c257384ef 100644 --- a/examples/widgets/arc/index.rst +++ b/examples/widgets/arc/index.rst @@ -4,6 +4,7 @@ Simple Arc .. lv_example:: widgets/arc/lv_example_arc_1 :language: c + :description: A simple example to demonstrate the use of an arc. Loader with Arc """"""""""""""""