#6583 document location of maven cache, M2_HOME envar, classpath rese…

…t, local repositories

doc/groovy/ClasspathMagicCommands.ipynb

@@ -221,9 +221,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Loading multiple Dependencies with Maven\n",
+    "## Loading Multiple Dependencies with Maven\n",
     "\n",
-    "You can use `%%classpath` cell magic to load multiple dependencies at once. Cell magic will create POM file that will contain all dependencies listed in cell."
+    "Use the `%%classpath` cell magic to load multiple dependencies at once. This magic creates a POM file containing all the dependencies listed in the cell, solves them together with Maven, and adds the result to the classpath."
    ]
   },
   {
@@ -243,7 +243,7 @@
    "source": [
     "## Loading Jars from a Dynamic Location\n",
     "\n",
-    "The above magics work on literal strings.  If you need to compute the location of a jar, use the dynamic classpath magic:"
+    "The above magics work on literal strings.  If you need to compute the location of a jar, use the dynamic classpath magic.  It has two versions one that works with a single string, and another that takes a list of strings:"
    ]
   },
   {
@@ -273,6 +273,48 @@
     "%classpath add dynamic [location + \"demo.jar\", location + \"BeakerXClasspathTest.jar\"]"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Location of the Maven Cache and Using a Local Repository\n",
+    "\n",
+    "Maven normally downloads jars to `~/.m2/repository/`.  But unfortunately this cache is [not safe for concurrent access](https://issues.apache.org/jira/browse/MNG-2802).\n",
+    "To avoid corrupting it, BeakerX by default uses its own Maven cache in the conda environment at `$(CONDA_PREFIX)/share/beakerx/maven`.  The `M2_HOME` environment variable overrides the default if set.\n",
+    "\n",
+    "If you want to use a normal IDE to develop a library, publish it to your local Maven repository, and then load that library into BeakerX, you can, like this:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%classpath config resolver mvnLocal"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "That is shorthand for a `%classpath config resolver local` magic with a `file:` path to the local repository.\n",
+    "\n",
+    "## Clearing the Maven Cache\n",
+    "\n",
+    "If you have painted yourself into a corner, you can clear the contents of the maven cache as follows.\n",
+    "This is useful for example if you have locally published [non-snapshot artifacts](https://maven.apache.org/guides/getting-started/index.html#What_is_a_SNAPSHOT_version). After resetting the cache, you will be prompted to restart your kernel."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%classpath reset"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},