added new docs pages and modified some examples

Author: DenisaCG

docs/_static/commentBlock.png

@@ -4,4 +4,14 @@ The Blockly editor is mainly composed of two elements: the **toolbox**, situated
 
 ![Blockly Demo](_static/shortBlocklyDemo.gif)
 
+## Executing your code
+
 Once you think your code is ready you can press the **Run** button, found in the upper-left corner. The generated code in the chosen programming language will appear at the bottom of the screen in a Juypter code cell, along with the output.
+
+## Modifying your code
+
+You have full freedom to change the position of any blocks in the workspace, as well as remove the ones you don't want to use anymore, by dragging them to the trash bin positioned at the bottom-right corner.
+
+You can also organize your code in multiple sets of blocks. The generated code will be rendered in the order they are placed on the screen.
+
+**NOTE** : By right clicking anywhere on the workspace you can get a set of possible commands, such as _Undo_, _Redo_ or _Delete # Blocks_. This gives you more freedom to edit of your canvas.

docs/_static/creatingVariable.gif

@@ -1,7 +1,41 @@
 # Examples
 
-- logic
-- loops
-- lists_texts
-- variables
-- functions
+To help gain a better understanding of the JupyterLab-Blockly, we created some examples you can easily access and experiment with. They can be accessed from the folder `examples` in the [Github repository](https://github.com/QuantStack/jupyterlab-blockly/tree/main/examples).
+
+The examples give you a chance to be introduced to the most important blocks and their functionalities. The extension is a great tool for introducing the most relevant concepts of coding by also letting you see the rendered code. Once you have gotten a good grasp on it, you can easily use the familiar Jupyter enviroment to move to another classical programming language, such as Python.
+
+## Logic Blocks Example
+
+The example in `logic.jpblockly` takes a random integer and checks if it respects certain conditions, through a series of `if-else` statements, and returns appropiate messages.
+
+**NOTE** : Any block that has the settings icon in the upper-left corner offers the possibility of adding extra fields, thus you can modify the `if` standard block to adapt to your code by adding the needed `else if` or `else` clauses.
+
+<p align="center">
+  <img src="_static/ifBlock.gif" alt="Modifying if block"/>
+</p>
+
+## Loop Blocks Example
+
+In `loops.jpblockly`, we use a standard loop with initial condition to iterate from 1 to 15 and print a message at each step and one to mark the exit from the loop.
+
+In order to iterate through the loop, we created a variable `count`. You can create variables by simply accessing the **Variables** category from the toolbox and pressing the button _Create variable..._. Once you have named and created your variable, a new selection of blocks will appear for it in the category.
+
+<p align="center">
+  <img src="_static/creatingVariable.gif" alt="Creating a variable"/>
+</p>
+
+## Texts and Lists Blocks Example
+
+In the `text_and_lists.jpblockly` example, we are using several of the offered blocks from the two categories, to modify or offer information from a string saved in the variable `sentence`.
+
+## Function and Color Blocks Example
+
+In `functions.jpblockly`, we are creating a function `blend colors` which takes two randomly chosen colors and returns a new color, formed by blending the inputs, using a `color` block.
+
+When creating a function, you can choose a name for it, the number of inputs (by pressing the settings icon), whether it has an output or not and write a comment for it to explain its functionality (by pressing the question mark icon).
+
+<p align="center">
+  <img src="_static/commentBlock.png" alt="Function block with comment"/>
+</p>
+
+**NOTE** : You can add a comment to any icon by right clicking on it and choosing `Add comment`. The added text will appear in the generated code, above the selected block as a comment.

docs/_static/darkBlockly.png

@@ -8,6 +8,8 @@ Welcome to jupyterlab-blockly's documentation!
 
 This JupyterLab extension brings block-based programming directly to your web browser. You can easily use the JupyterLab-Blockly editor and choose from a wide selections of blocks to start coding, see the output of your code and, most importantly, visualize the code transformed in the chosen classical programming language. 
 
+The extension uses `Blockly <https://developers.google.com/blockly>`_, an open source library designed by Google. 
+
 .. image:: _static/OverviewBlockly.gif
    :alt: Functionality of extension
 
@@ -25,8 +27,15 @@ This JupyterLab extension brings block-based programming directly to your web br
    blockly_editor
    kernels
    toolbox
+   jupyterlab_integration
    examples
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Expanding:
+
+   other_extensions
+
 Indices and tables
 ==================
 

docs/_static/ifBlock.gif

@@ -0,0 +1,21 @@
+# JupyterLab Integration
+
+The JupyterLab-Blockly extension is fully integrated in the Jupyter enviroment to offer a seamless experience to the user. Thus, the Blockly editor automatically adapts to any modyfication you make to JupyterLab's appearance.
+
+## Theme
+
+The Blockly editor changes its theme in accordance to the JupyterLab one, whether it's the standard light or dark ones or a personalized one.
+
+Below is an example of how the Blockly editor looks with the dark theme.
+
+![Blockly with the dark theme](_static/darkBlockly.png)
+
+You can experiment with this by pressing "Settings" > "Theme", from the JupyterLab toolbar.
+
+## Internalization
+
+If you prefer using JupyterLab in another language, the Blockly editor can also render its blocks and additional messages (visible by right clicking on any block or in the workspace) in the selected language.
+
+The extension can be rendered in all the languages available in JupyterLab. A complete list can be seen [here](https://github.com/jupyterlab/language-packs/tree/master/language-packs).
+
+**NOTE** : This feature is a work in progress, so the names of the categories from the toolbox are only offered in English so far.

docs/blockly_editor.md

@@ -0,0 +1,3 @@
+# Other extensions
+
+... instructions on how to built on top of the JupyterLab-Blockly extension

docs/examples.md

@@ -11,3 +11,5 @@ The toolbox, a main element of the Blockly editor, is situated on the left side
 If you have installed or created another extension, on top of the JupyterLab-Blockly extension, which includes a new tooolbox, you can switch to it by simply pressing the drop down menu on the upper-right corner.
 
 ![Switch Toolbox](_static/toolboxSwitch.png)
+
+**NOTE** : The toolbox `niryo` from the image above is part of the JupyterLab-Niryo-One extension, which is built on top of the JupyterLab-Blockly extesnion and is meant to offer blocks which can control the Niryo One robot. You can read more about it on its [Github repository](https://github.com/QuantStack/jupyterlab-niryo-one).

docs/index.rst

@@ -1 +1 @@
-{"blocks":{"languageVersion":0,"blocks":[{"type":"procedures_defreturn","id":"%8PNf28db!8zx+dd?%ji","x":675,"y":61,"extraState":{"params":[{"name":"x","id":"q0cacp9:z4~OoAPJD;,C"},{"name":"y","id":"CW(vE:rK%t[x6D3u2o^E"}]},"icons":{"comment":{"text":"Given two colors blend them together and return the new color.","pinned":false,"height":80,"width":160}},"fields":{"NAME":"blend colors"},"inputs":{"STACK":{"block":{"type":"variables_set","id":"yhtLWu1UAK8q6UnM42:*","fields":{"VAR":{"id":"^g2Uj9MfJG$l7y429CXC"}},"inputs":{"VALUE":{"block":{"type":"colour_blend","id":"Z[NU~CekM,dcy6s5g`jT","inputs":{"COLOUR1":{"shadow":{"type":"colour_picker","id":"MJcF7laq2[($byO:zY!z","fields":{"COLOUR":"#ff0000"}},"block":{"type":"variables_get","id":"IEN9YD}{-#M]pHAlxx.$","fields":{"VAR":{"id":"q0cacp9:z4~OoAPJD;,C"}}}},"COLOUR2":{"shadow":{"type":"colour_picker","id":"8qEW3`30@u!4gVyBaLDX","fields":{"COLOUR":"#ffffff"}},"block":{"type":"variables_get","id":"~K:*1w)X0sk*I0VLYQHr","fields":{"VAR":{"id":"CW(vE:rK%t[x6D3u2o^E"}}}},"RATIO":{"shadow":{"type":"math_number","id":"N?$vgO28idfY^ot|B2Gf","fields":{"NUM":0.5}}}}}}}}},"RETURN":{"block":{"type":"variables_get","id":"U_JpRYt5d|/CIoPllP1g","fields":{"VAR":{"id":"^g2Uj9MfJG$l7y429CXC"}}}}}},{"type":"variables_set","id":",kwuc=NJCZ@[bAACvz*|","x":-3,"y":76,"fields":{"VAR":{"id":"Hfm;!%[BIJL%q3lMPG+C"}},"inputs":{"VALUE":{"block":{"type":"colour_random","id":"CbbTVSYni`e*:?x?rmlV"}}},"next":{"block":{"type":"variables_set","id":"#jL#GO%p{@PE}!AjShPo","fields":{"VAR":{"id":"Ha!q|23ni|13^3=2}4!q"}},"inputs":{"VALUE":{"block":{"type":"colour_random","id":"7DV=;7eTBYT[:gu-LjE7"}}},"next":{"block":{"type":"text_print","id":"y-JhP(a9@pY?WfnS@F!q","inputs":{"TEXT":{"shadow":{"type":"text","id":"+ENEt4:6#@7zoKnQWfi`","fields":{"TEXT":"abc"}},"block":{"type":"text_join","id":"i_u9:RFgY`,HeN!2[NXt","extraState":{"itemCount":2},"inputs":{"ADD0":{"block":{"type":"text","id":"!q/c.uj`^4rimA,zLirP","fields":{"TEXT":"Initial colors: "}}},"ADD1":{"block":{"type":"text_join","id":"m3UhYbtgIc3q,vsAs4Mp","extraState":{"itemCount":2},"inputs":{"ADD0":{"block":{"type":"variables_get","id":"vChfBN5W]+gN1bF5m{{D","fields":{"VAR":{"id":"Hfm;!%[BIJL%q3lMPG+C"}}}},"ADD1":{"block":{"type":"text_join","id":"GIwKm=BD=H;uFtL0kpN/","extraState":{"itemCount":2},"inputs":{"ADD0":{"block":{"type":"text","id":"lx{9H+ej.BL)_,nno[se","fields":{"TEXT":" and "}}},"ADD1":{"block":{"type":"variables_get","id":"|3!]gyVuu,SWNg-Ej2UQ","fields":{"VAR":{"id":"Ha!q|23ni|13^3=2}4!q"}}}}}}}}}}}}}},"next":{"block":{"type":"text_print","id":"!9GpxWxAuFu}RXlKwwKU","inputs":{"TEXT":{"shadow":{"type":"text","id":"+ENEt4:6#@7zoKnQWfi`","fields":{"TEXT":"abc"}},"block":{"type":"text_join","id":"^O7k|#/QVw64tkQzE,jL","extraState":{"itemCount":2},"inputs":{"ADD0":{"block":{"type":"text","id":"g8*hkX]y2W1DtmOG{YDt","fields":{"TEXT":"Blended color: "}}},"ADD1":{"block":{"type":"procedures_callreturn","id":"a=?]IhVl5[)h`)efB^2K","extraState":{"name":"blend colors","params":["x","y"]},"inputs":{"ARG0":{"block":{"type":"variables_get","id":";lny}q%LI*45*$Vwu/7a","fields":{"VAR":{"id":"Hfm;!%[BIJL%q3lMPG+C"}}}},"ARG1":{"block":{"type":"variables_get","id":"HaW6U=VZzQLn-:}KbLB[","fields":{"VAR":{"id":"Ha!q|23ni|13^3=2}4!q"}}}}}}}}}}}}}}}}}}]},"variables":[{"name":"color_1","id":"Hfm;!%[BIJL%q3lMPG+C"},{"name":"x","id":"q0cacp9:z4~OoAPJD;,C"},{"name":"y","id":"CW(vE:rK%t[x6D3u2o^E"},{"name":"color_2","id":"Ha!q|23ni|13^3=2}4!q"},{"name":"blend","id":"^g2Uj9MfJG$l7y429CXC"}]}
+{"blocks":{"languageVersion":0,"blocks":[{"type":"procedures_defreturn","id":"%8PNf28db!8zx+dd?%ji","x":675,"y":61,"extraState":{"params":[{"name":"x","id":"q0cacp9:z4~OoAPJD;,C"},{"name":"y","id":"CW(vE:rK%t[x6D3u2o^E"}]},"icons":{"comment":{"text":"Given two colors blend them together and return the new color.","pinned":false,"height":80,"width":160}},"fields":{"NAME":"blend colors"},"inputs":{"STACK":{"block":{"type":"variables_set","id":"yhtLWu1UAK8q6UnM42:*","fields":{"VAR":{"id":"^g2Uj9MfJG$l7y429CXC"}},"inputs":{"VALUE":{"block":{"type":"colour_blend","id":"Z[NU~CekM,dcy6s5g`jT","inputs":{"COLOUR1":{"shadow":{"type":"colour_picker","id":"MJcF7laq2[($byO:zY!z","fields":{"COLOUR":"#ff0000"}},"block":{"type":"variables_get","id":"IEN9YD}{-#M]pHAlxx.$","fields":{"VAR":{"id":"q0cacp9:z4~OoAPJD;,C"}}}},"COLOUR2":{"shadow":{"type":"colour_picker","id":"8qEW3`30@u!4gVyBaLDX","fields":{"COLOUR":"#ffffff"}},"block":{"type":"variables_get","id":"~K:*1w)X0sk*I0VLYQHr","fields":{"VAR":{"id":"CW(vE:rK%t[x6D3u2o^E"}}}},"RATIO":{"shadow":{"type":"math_number","id":"N?$vgO28idfY^ot|B2Gf","fields":{"NUM":0.5}}}}}}}}},"RETURN":{"block":{"type":"variables_get","id":"U_JpRYt5d|/CIoPllP1g","fields":{"VAR":{"id":"^g2Uj9MfJG$l7y429CXC"}}}}}},{"type":"variables_set","id":",kwuc=NJCZ@[bAACvz*|","x":-3,"y":76,"fields":{"VAR":{"id":"Hfm;!%[BIJL%q3lMPG+C"}},"inputs":{"VALUE":{"block":{"type":"colour_random","id":"CbbTVSYni`e*:?x?rmlV"}}},"next":{"block":{"type":"variables_set","id":"#jL#GO%p{@PE}!AjShPo","fields":{"VAR":{"id":"Ha!q|23ni|13^3=2}4!q"}},"inputs":{"VALUE":{"block":{"type":"colour_random","id":"7DV=;7eTBYT[:gu-LjE7"}}},"next":{"block":{"type":"text_print","id":"y-JhP(a9@pY?WfnS@F!q","inputs":{"TEXT":{"shadow":{"type":"text","id":"+ENEt4:6#@7zoKnQWfi`","fields":{"TEXT":"abc"}},"block":{"type":"text_join","id":"i_u9:RFgY`,HeN!2[NXt","extraState":{"itemCount":2},"inputs":{"ADD0":{"block":{"type":"text","id":"!q/c.uj`^4rimA,zLirP","fields":{"TEXT":"Initial colors: "}}},"ADD1":{"block":{"type":"text_join","id":"m3UhYbtgIc3q,vsAs4Mp","extraState":{"itemCount":3},"inputs":{"ADD0":{"block":{"type":"variables_get","id":"vChfBN5W]+gN1bF5m{{D","fields":{"VAR":{"id":"Hfm;!%[BIJL%q3lMPG+C"}}}},"ADD1":{"block":{"type":"text","id":"lx{9H+ej.BL)_,nno[se","fields":{"TEXT":" and "}}},"ADD2":{"block":{"type":"variables_get","id":"|3!]gyVuu,SWNg-Ej2UQ","fields":{"VAR":{"id":"Ha!q|23ni|13^3=2}4!q"}}}}}}}}}}},"next":{"block":{"type":"text_print","id":"!9GpxWxAuFu}RXlKwwKU","inputs":{"TEXT":{"shadow":{"type":"text","id":"+ENEt4:6#@7zoKnQWfi`","fields":{"TEXT":"abc"}},"block":{"type":"text_join","id":"^O7k|#/QVw64tkQzE,jL","extraState":{"itemCount":2},"inputs":{"ADD0":{"block":{"type":"text","id":"g8*hkX]y2W1DtmOG{YDt","fields":{"TEXT":"Blended color: "}}},"ADD1":{"block":{"type":"procedures_callreturn","id":"a=?]IhVl5[)h`)efB^2K","extraState":{"name":"blend colors","params":["x","y"]},"inputs":{"ARG0":{"block":{"type":"variables_get","id":";lny}q%LI*45*$Vwu/7a","fields":{"VAR":{"id":"Hfm;!%[BIJL%q3lMPG+C"}}}},"ARG1":{"block":{"type":"variables_get","id":"HaW6U=VZzQLn-:}KbLB[","fields":{"VAR":{"id":"Ha!q|23ni|13^3=2}4!q"}}}}}}}}}}}}}}}}}}]},"variables":[{"name":"color_1","id":"Hfm;!%[BIJL%q3lMPG+C"},{"name":"x","id":"q0cacp9:z4~OoAPJD;,C"},{"name":"y","id":"CW(vE:rK%t[x6D3u2o^E"},{"name":"color_2","id":"Ha!q|23ni|13^3=2}4!q"},{"name":"blend","id":"^g2Uj9MfJG$l7y429CXC"}]}