Cleanup devdocs.

Author: alshan

devdocs/JUPYTER_KOTLIN_KERNEL.md

@@ -1,84 +1,64 @@
-## Install:
-`$ pip install kotlin-jupyter-kernel`
-
-## Install dev:
-`$ pip install -i https://test.pypi.org/simple/ kotlin-jupyter-kernel`
-
-## Build and install Kernel from sources:
-Github: https://github.com/Kotlin/kotlin-jupyter
+## Installing Kotlin Kernel
 
-`$ ./gradlew install`
-
-If built successfully it will install the kernel to:   
-> ~/.ipython/kernels/kotlin
+`$ pip install kotlin-jupyter-kernel`
 
-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`:  
 > /opt/anaconda3/envs/<env name>/lib/python3.7/site-packages/run_kotlin_kernel/libraries/
 
-b) After installing from local sources via `$ ./gradlew install`:  
-> ~/.jupyter_kotlin/cache/libraries/
-
-> [!NOTE]  
-> If the `%useLatestDescriptors` **_line magic_** is included in Jupyter notebook,
+> **Note:** If the `%useLatestDescriptors` **_line magic_** is included in Jupyter notebook,
+> 
 > Kotlin kernel will pull the latest repository version of descriptors and store them in this location:
->
 > ~/.jupyter_kotlin/cache/
+> 
          
+## Notebook Tips and Tricks
 
-## 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.
-
-
---------
-In notebook
-
-`:classpath` - shows all resolved jars.
-
-`%useLatestDescriptors` - will force Kotlin Kernel to pull and apply the latest repository version of all library descriptors.
-Descriptors location:
-~/.jupyter_kotlin/cache
+- show all resolved jars:
+  ```
+  :classpath
+  ```
 
-Otherwise, Kotlin Kernel uses 'bundled' descriptors installed to:
-> /opt/anaconda3/envs/<env name>/lib/python3.7/site-packages/run_kotlin_kernel/libraries
+- force the Kotlin Kernel to pull from the repository and apply the latest versions of all library descriptors::
+  ```
+  %useLatestDescriptors
+  ```
 
-## Conducting experiments with Kotlin Kernel locally.
+- substitute the Kernel's version of the `lets-plot` library descriptor with your own descriptor:
+  ```
+  //%use lets-plot
+  %use @/Users/me/Projects/lets-plot-kotlin/lets-plot-dev.json
+  ```
+ 
+## Conducting Experiments with Kotlin Kernel Locally
 
 Clear Maven cache:
 `$ rm -rf ~/.m2/repository/org/jetbrains/lets-plot`                          
 
-#### 1) Publish artifacts to the local dev-repo:
-
-`./gradlew publishJvmPublicationToMavenLocalRepository`
-`./gradlew publishLetsPlotKotlinGeoToolsPublicationToMavenLocalRepository`
-`./gradlew publishletsPlotKotlinJupyterPublicationToMavenLocalRepository`
-`./gradlew publishletsPlotKotlinGeotoolsJupyterPublicationToMavenLocalRepository`
-`./gradlew publishLetsPlotKotlinJsonPublicationToMavenLocalRepository`
+#### Publish artifacts to the local dev-repo:
+                                                     
+```bash
+./gradlew publishJvmPublicationToMavenLocalRepository
+./gradlew publishLetsPlotKotlinGeoToolsPublicationToMavenLocalRepository
+./gradlew publishletsPlotKotlinJupyterPublicationToMavenLocalRepository
+./gradlew publishletsPlotKotlinGeotoolsJupyterPublicationToMavenLocalRepository
+./gradlew publishLetsPlotKotlinJsonPublicationToMavenLocalRepository
+```
 
 It will publish all artifacts to `<project root>/.maven-publish-dev-repo/` folder.
 
-#### 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.
-
-
-**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
-```
+#### Edit the library descriptor (lets-plot.json or lets-plot-gt.json):
 
+> **Tip:** To make sure you have the latest version of the descriptor in "~/.jupyter_kotlin/cache", 
+> execute the `%use lets-plot` statement in the notebook.
+> The kernel will download a newer descriptor if available.
+            
 - add _Maven Local_ or _Sonatype SNAPSHOT_ repository or both:
   ```
   "repositories": [
@@ -87,15 +67,21 @@ The kernel can download a newer descriptor at any moment.
   ],
   ```
 
-- configure the artifacts version (published Lets-Plot JS):
+- configure the Lets-Plot Kotlin version (the one that is set in `build.gradle.kts`):
   ```
   "properties": {
     "v": "3.1.2-alpha2",
     "isolatedFrame": ""
   },
   ```
+ 
 - if experimenting with Lets-Plot JS which is not published:
   - Set "js" version to "dev";
+> **TBD:** Currently there is no clean way to configure "dev" version for JS.
+> The "dirty" way is to add "dev" to the "js" version right in the `VersionChecker.kt`.
+> 
+> See the `letsPlotJsVersion` property in the `VersionChecker.kt` file.
+> 
   - 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: