update docs

Author: b3b

README.rst

@@ -22,24 +22,43 @@ PythonHere
     :alt: Code coverage Status
 .. end-badges
 
-Here` is the `Kivy <https://kivy.org>`_ based app to run Python code from the `Jupyter <https://jupyter.org/>`_ magic %there.
+*Here* is the `Kivy <https://kivy.org>`_ based app to run Python code from the `Jupyter <https://jupyter.org/>`_ magic %there.
 
 - *Here* is a server part with the GUI interface. It could be Android, Raspberry Pi, some other remote device that being debugged.
 - And *%there* is a client - Jupyter magic command to run code interactively on remote device.
 
 
+.. |jupyter| image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/left_jupyter.png
+   :align: middle
+   :height: 400
+.. |android| image:: https://raw.githubusercontent.com/b3b/pythonhere/master/docs/right_android.png
+   :align: middle
+   :height: 400
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Jupyter on PC
+     - Android app
+   * - |jupyter|
+     - |android|
+
+Project documentation: https://herethere.me
+
+
 Install on Android
 ------------------
 
-Ready-to-use `PythonHere` APKs are available in the `Releases <https://github.com/b3b/pythonhere/releases>`_ section.
+Ready-to-use *PythonHere* APKs are available in the `Releases <https://github.com/b3b/pythonhere/releases>`_ section.
 
 For a list of installed Python packages, see: `buildozer.spec <./buildozer.spec>`_.
 
 
 Quick Start with Docker
 -----------------------
 
-Docker image is based on `Jupyter Docker Stacks <https://jupyter-docker-stacks.readthedocs.io/en/latest/>`_, and includes installed `PythonHere` with usage examples.
+Docker image is based on `Jupyter Docker Stacks <https://jupyter-docker-stacks.readthedocs.io/en/latest/>`_, and includes installed *PythonHere* with usage examples.
 
 Example command to start the Docker container::
 
@@ -56,18 +75,37 @@ Files from the directory **work** inside container, will be available in the hos
 
 
 Run with Docker Compose
-^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
 
-Commands to run with Docker Compose::
+Commands to run with Docker Compose, in the source directory:::
 
   cp docker-compose.yml.tmpl docker-compose.yml
   docker-compose up
 
 
+Run locally
+-----------
+
+Commands to run locally::
+
+   pip install pythonhere
+   jupyter notebook start
+
+
+Build Android app
+-----------------
+
+To build with `Buildozer <https://github.com/kivy/buildozer>`_, run in the source directory::
+
+
+  buildozer android debug
+
+
+
 Related resources
 -----------------
 
 * `Kivy Remote Shell <https://github.com/kivy/kivy-remote-shell>`_: Remote SSH+Python interactive shell application
 * `herethere <https://github.com/b3b/herethere>`_ : Library for interactive code execution, based on AsyncSSH
 * `AsyncSSH <https://github.com/ronf/asyncssh>`_ : Asynchronous SSH for Python
-* `Buildozer action <https://github.com/ArtemSBulgakov/buildozer-action>`_ : GitHub action that is used to build Android APK with `Buildozer <https://github.com/kivy/buildozer>`_
+* `Buildozer action <https://github.com/ArtemSBulgakov/buildozer-action>`_ : GitHub action that is used to build Android APK with Buildozer

docs/left_jupyter.png

@@ -0,0 +1,182 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.2'
+      jupytext_version: 1.7.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+# Jupyter magic commands
+
+Commands are provided by the *pythonhere* extension
+
+```python
+%load_ext pythonhere
+```
+
+## connect-there
+**Connect to remote interpreter via SSH.**
+
+Command takes single optional argument: location of connection config.<br>
+If argument is not provided, values are loaded from the **there.env** file.
+
+Config values could be overridden by environment variables with same names.
+
+```python
+import os
+os.environ["THERE_PORT"] = "8022"
+```
+
+```python
+%connect-there there.env
+```
+
+### there.env example
+```
+# PythonHere device IP address
+THERE_HOST=127.0.0.1
+
+# Port, as set in PythonHere app Settings section
+THERE_PORT=8023
+
+# Username, as set in PythonHere app Settings section
+THERE_USERNAME=admin
+
+# Password, as set in PythonHere app Settings section
+THERE_PASSWORD=xxx
+```
+
+
+## %there group of commands
+
+```python
+%there --help
+```
+
+Default action for *%there*, if command is not specified - execute python code.
+
+
+## there
+**Execute python code on the remote side.**<br>
+
+```python
+%%there 
+import this
+```
+
+## kv
+
+```python
+%there kv --help
+```
+
+If option `--clear-style` is provided,<br> all previous rules, that was loaded with *%%there kv* command,
+are unloaded before command execution.
+
+If root widget is defined, it will replace App's current root.
+
+
+
+```python
+%%there kv
+Image:
+    source: "../app/data/logo/logo-128.png"
+    canvas.before:
+        PushMatrix
+        Rotate:
+            angle: 45
+            origin: self.center
+    canvas.after:
+        PopMatrix
+```
+
+## shell
+
+```python
+%there shell --help
+```
+
+```python
+%%there shell
+pwd
+```
+
+```python
+%%there shell
+for i in 1 2 3
+do
+    echo -n "$i"
+done
+```
+
+<!-- #region hideCode=false -->
+Listen to Android system logs in the background and show last two lines of output:
+<!-- #endregion -->
+
+```python
+%%there -bl 2 shell
+logcat
+```
+
+## upload
+
+```python
+%there upload --help
+```
+
+*upload* root directory is application current working directory.
+
+```python
+!touch some.ico script.py
+!mkdir -p dir1/dir2
+```
+
+```python
+%there upload some.ico script.py dir1 ../
+```
+
+```python
+%%there shell
+find
+```
+
+## log
+
+```python
+%there log --help
+```
+
+```{note}
+Since the command blocks and never ends, it is useful to run with --backgroud (-b) option
+```
+
+```python
+%there -bl 1 log
+```
+
+```python
+%%there
+from kivy.logger import Logger
+Logger.info("Hello from the future cell")
+```
+
+## screeenshot
+
+```python
+%there screenshot --help
+```
+
+* Wait for half of a second before a command execution,<br>
+* make a screenshot,
+* display a result constrained to 200px width,
+* and save image to a local file:
+
+```python
+%there -d .5 screenshot -w 200 -o /tmp/screenshot_test.png
+```

docs/right_android.png

@@ -0,0 +1,66 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.2'
+      jupytext_version: 1.7.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+# Execution environment
+
+```python
+%load_ext pythonhere
+%connect-there
+```
+
+Commands are executed in the application main thread, thread is blocked until the end of a cell code execution.<br>
+On first SSH connection, BoxLayout is set as a root widget.
+
+Variables in the scope of the *%there* command:
+* **app** - Kivy application instance
+* **root** - current root widget
+
+```python
+%%there
+print(app)
+print(root)
+```
+
+## KV rules
+*%there kv* rules processing is different from the normal Kivy behavior.<br>
+When class is registered for second time with the same name, previous declaration for that class is deleted.
+
+```python
+%%there kv
+<MyButton@Button>:
+    color: "orange"
+    text: "Orange"
+        
+MyButton:
+    font_size: 100
+```
+
+```python
+%there screenshot -w 200
+```
+
+```python
+%%there kv
+<MyButton@Button>:
+    text: "Orange?"
+        
+MyButton:
+    font_size: 100
+```
+
+`color: "orange"` rule is removed:
+
+```python
+%there screenshot -w 200
+```

examples/commands.md

@@ -27,10 +27,7 @@
     "-c", "--clear-style", is_flag=True, help="Unload previously applied rules"
 )
 def kv(code: str, clear_style: bool) -> str:
-    """Insert given rules into the Kivy Language Builder.
-
-    :param code: KV language rules
-    """
+    """Insert given rules into the Kivy Language Builder."""
     code = "# %%there ... \n" + code.replace("'''", '"""')
     return KV_COMMAND_TEMPLATE.format(code=code, clear_style=clear_style)
 

examples/environment.md

@@ -51,7 +51,7 @@
     url="https://github.com/b3b/ipython-pythonhere",
     # https://pypi.org/classifiers/
     classifiers=[
-        "Development Status :: 2 - Pre-Alpha",
+        "Development Status :: 3 - Alpha",
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
     ],