Improve devdocs.

Author: alshan

devdocs/JUPYTER_KOTLIN_KERNEL.md

@@ -1,35 +1,30 @@
-Install:
---------
-pip install kotlin-jupyter-kernel
+## Install:
+`$ pip install kotlin-jupyter-kernel`
 
-Install dev:
-------------
-`pip install -i https://test.pypi.org/simple/ kotlin-jupyter-kernel`
+## Install dev:
+`$ pip install -i https://test.pypi.org/simple/ kotlin-jupyter-kernel`
 
-Build and install Kernel from sources:
---------------------------------------
+## Build and install Kernel from sources:
 Github: https://github.com/Kotlin/kotlin-jupyter
 
-`./gradlew install`
+`$ ./gradlew install`
 
 If built successfully it will install the kernel to:   
 > ~/.ipython/kernels/kotlin
 
 Normally the kernel is installed to conda env.
 
-
-Library descriptors location
------------------------------
+## Library descriptors location
 Lets-Plot library descriptors are files:
 - lets-plot.json
 - lets-plot-gt.json
 
 After installing kotlin kernel the "bundled" library descriptors are located in
 
-a) After installing via `pip install`:  
+a) After installing via `$ pip install`:  
 > /opt/anaconda3/envs/<env name>/lib/python3.7/site-packages/run_kotlin_kernel/libraries/
 
-b) After installing from local sources via `./gradlew install`:  
+b) After installing from local sources via `$ ./gradlew install`:  
 > ~/.jupyter_kotlin/cache/libraries/
 
 **Note:** If the `%useLatestDescriptors` **_line magic_** is included in Jupyter notebook,  
@@ -39,8 +34,7 @@ b) After installing from local sources via `./gradlew install`:
 > ~/.jupyter_kotlin/cache/
          
 
-About library descriptors (lets-plot.json, lets-plot-gt.json)
-------------------------------------------------------------
+## About library descriptors (lets-plot.json, lets-plot-gt.json)
 
  - edit descriptor: to conduct local experiments (see more info below).
  - remove descriptor: force the kernel to pull current published version of descriptor from 'master' at https://github.com/Kotlin/kotlin-jupyter.
@@ -58,44 +52,48 @@ Descriptors location:
 Otherwise, Kotlin Kernel uses 'bundled' descriptors installed to:
 > /opt/anaconda3/envs/<env name>/lib/python3.7/site-packages/run_kotlin_kernel/libraries
 
---------
-Conducting experiments with Kotlin Kernel locally.
---------------------------------------------------
+## Conducting experiments with Kotlin Kernel locally.
 
-- Publish artifacts to the local dev-repo:
+#### 1) Publish artifacts to the local dev-repo:
 
 `$ ./gradlew publishLetsPlotKotlinKernelPublicationToMavenLocalRepository`  
 `$ ./gradlew publishLetsPlotKotlinGeoToolsPublicationToMavenLocalRepository`
 
 It will publish `lets-plot-kotlin-api-kernel-<version>` artifact to the `<project root>/.maven-publish-dev-repo/` folder.
 
-- edit "lets-plot.json" (see info above about its location):
-
-    - add Maven Local repository:
-      ```
-      "repositories": [
-        "file://<path to the project root>/.maven-publish-dev-repo"
-      ],
-      ```
-  
-    - configure the artifact (i.e. "api") version, for example:
-      ```
-      "properties": {
-        "api": "3.1.2-alpha2",
-        "lib": "2.3.0-rc2",
-        "js": "2.3.0rc2",
-        "isolatedFrame": ""
-      },
-      ```
-
+#### 2) Edit "lets-plot.json" (see info above about its location):
 
 **Note:** when editing descriptor in "~/.jupyter_kotlin/cache" always check that you are using the latest descriptor.  
 The kernel can download a newer descriptor at any moment.
 
-**Note:** to use SNAPSHOTS from Sonatype repository, add the following repository to the descriptor:
-`"https://oss.sonatype.org/content/repositories/snapshots"`
 
-**Alternatively**, if you do not want to rely on a "cached" descriptor, you can load any of your library descriptors using the **_line magic_**: 
+**Alternatively**, if you do not want to rely on a "cached" descriptor, you can load any of your library descriptors using the **_line magic_**:
 ```
+//%use lets-plot
 %use @/Users/me/Projects/lets-plot-kotlin/lets-plot-dev.json
-```
+```
+
+- add _Maven Local_ or _Sonatype SNAPSHOT_ repository or both:
+  ```
+  "repositories": [
+    "file://<path to the project root>/.maven-publish-dev-repo",
+    "https://oss.sonatype.org/content/repositories/snapshots"
+  ],
+  ```
+
+- configure the artifacts version (published Lets-Plot JS):
+  ```
+  "properties": {
+    "api": "3.1.2-alpha2",
+    "lib": "2.3.0-rc2",
+    "js": "2.3.0rc2",
+    "isolatedFrame": ""
+  },
+  ```
+- if experimenting with Lets-Plot JS which is not published:
+  - Set "js" version to "dev";
+  - Build "dev" JS package (see [lets-plot/js-package/README.md](https://github.com/JetBrains/lets-plot/blob/master/js-package/README.md));
+  - Activate any "env" containing Python;
+  - Start local HTTP-server serving the JS dev-version:
+    - `$ cd lets-plot` 
+    - `$ python -m http.server 8000`