update docs

Author: b3b

README.rst

@@ -78,8 +78,8 @@ Run locally
 
 Commands to run locally::
 
-   pip install pythonhere
-   jupyter notebook start
+   pip install pythonhere jupyter
+   jupyter notebook
 
 
 Build Android app

examples/android.md

@@ -118,6 +118,24 @@ cat /sdcard/test_python_here.txt
 rm /sdcard/test_python_here.txt
 ```
 
+###  Application-specific directories
+Previous example will not work on Android >= 10,
+
+because of privacy changes: https://developer.android.com/about/versions/10/privacy/changes#scoped-storage
+
+In this case, it is possible to use directories that owned by the application:
+
+```python
+%%there
+from jnius import autoclass, cast
+PythonActivity = autoclass('org.kivy.android.PythonActivity')
+Environment = autoclass('android.os.Environment')
+context = cast('android.content.Context', PythonActivity.mActivity)
+print(context.getExternalFilesDir(None).getAbsolutePath())
+print(context.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS).getAbsolutePath())
+print(context.getExternalFilesDir(Environment.DIRECTORY_PICTURES).getAbsolutePath())
+```
+
 ## Take picture with a camera
 Camera could be displayed and captured with the Kivy [Camera](https://kivy.org/doc/stable/api-kivy.uix.camera.html) widget.
 

examples/ble.md

@@ -13,7 +13,7 @@ jupyter:
 ---
 
 # Android Bluetooth Low Energy functions
-BLE functions could be used with the [able](https://github.com/b3b/able) library.
+BLE functions could be used with the [able](https://herethere.me/able) library.
 
 ```python
 %load_ext pythonhere

examples/commands.md

@@ -20,8 +20,8 @@ Commands are provided by the *pythonhere* extension
 %load_ext pythonhere
 ```
 
-## connect-there
-**Connect to remote interpreter via SSH.**
+## %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.
@@ -62,15 +62,15 @@ THERE_PASSWORD=xxx
 Default action for *%there*, if command is not specified - execute python code.
 
 
-## there
+### there
 **Execute python code on the remote side.**<br>
 
 ```python
 %%there 
 import this
 ```
 
-## kv
+### kv
 
 ```python
 %there kv --help
@@ -96,7 +96,7 @@ Image:
         PopMatrix
 ```
 
-## shell
+### shell
 
 ```python
 %there shell --help
@@ -124,7 +124,7 @@ Listen to Android system logs in the background and show last two lines of outpu
 logcat
 ```
 
-## upload
+### upload
 
 ```python
 %there upload --help
@@ -146,7 +146,18 @@ logcat
 find
 ```
 
-## log
+
+### pin
+
+```python
+%there pin --help
+```
+
+```python
+%there pin script.py --label "My script"
+```
+
+### log
 
 ```python
 %there log --help
@@ -157,16 +168,21 @@ Since the command blocks and never ends, it is useful to run with --backgroud (-
 ```
 
 ```python
-%there -bl 1 log
+%there -b -l 1 log
+```
+
+```python
+# wait, to make sure *log* cell connection is established before next cell is executed
+import asyncio ; await asyncio.sleep(3)
 ```
 
 ```python
 %%there
 from kivy.logger import Logger
-Logger.info("Hello from the future cell")
+Logger.info(f"Hello from the main cell")
 ```
 
-## screeenshot
+### screeenshot
 
 ```python
 %there screenshot --help
@@ -178,5 +194,5 @@ Logger.info("Hello from the future cell")
 * and save image to a local file:
 
 ```python
-%there -d .5 screenshot -w 200 -o /tmp/screenshot_test.png
+%there -d 0.5 screenshot -w 200 -o /tmp/screenshot_test.png
 ```

examples/midi.md

@@ -284,5 +284,5 @@ for code in list(midi_instruments.keys()):
 ```
 
 ```python
-%there screenshot -w 200
+%there -d 1 screenshot -w 200
 ```

examples/random_animation.md

@@ -0,0 +1,81 @@
+---
+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
+---
+
+# Some animation and effects with KV
+
+```python
+%load_ext pythonhere
+%connect-there
+```
+
+```python
+%%there kv
+#:import Animation kivy.animation.Animation
+#:import ew kivy.uix.effectwidget
+
+<Dancer@Button>:
+    moves: ("\(-_- )\\", "/( -_-)/")
+    font_size: 100
+    seq: 0
+    text: self.moves[int(self.seq)]
+    on_press: self.seq = int(not(self.seq))
+
+<Rotor@Image>:
+    angle: 360
+    allow_stretch: True
+    source: "../app/data/logo/logo-128.png"
+
+    canvas.before:
+        PushMatrix
+        Rotate:
+            angle: self.angle
+            origin: self.center
+    canvas.after:
+        PopMatrix
+
+    rotate: Animation(angle=0, duration=2) + Animation(angle=360, duration=0)
+    grow:
+        (
+        Animation(size=(300, 300), duration=.1) +
+        Animation(size=(100, 100), duration=.1) +
+        Animation(size=(100, 100), duration=.3)
+        )
+
+    on_parent:
+        self.rotate.repeat=True
+        self.grow.repeat=True
+        self.rotate.start(self)
+        self.grow.start(self)
+
+
+<RootLayout@FloatLayout>:
+    GridLayout:
+        cols: 2
+        Dancer:
+        Dancer:
+        Dancer:
+        Dancer:
+
+    EffectWidget:
+        effects: ew.ScanlinesEffect(),
+        AnchorLayout:
+            Rotor:
+                size_hint: None, None
+
+RootLayout:
+```
+
+```python
+%there -d 1 screenshot -w 200
+```

pythonhere/magic_here/shortcuts.py

@@ -80,7 +80,7 @@ def screenshot(ctx, width, output):
 @click.option("-l", "--label", type=str, default="", help="Label for shortcut")
 @click.argument("script", nargs=1)
 def pin(code: str, script: str, label: str) -> str:  # pylint: disable=unused-argument
-    """Create pinned shortcut to run a Python script."""
+    """Create pinned shortcut to run a Python script from Android home screen."""
     if not label:
         label = script.split("/")[-1]
     return PIN_COMMAND_TEMPLATE.format(script=script, label=label)