#2828 update notebook with documentation

Author: rjzupkoii

talkmap.ipynb

@@ -6,7 +6,21 @@
    "source": [
     "# Leaflet cluster map of talk locations\n",
     "\n",
-    "Run this from the _talks/ directory, which contains .md files of all your talks. This scrapes the location YAML field from each .md file, geolocates it with geopy/Nominatim, and uses the getorg library to output data, HTML, and Javascript for a standalone cluster map."
+    "Assuming you are working in a Linux or Windows Subsystem for Linux environment, you may need to install some dependencies. Assuming a clean installation, the following will be needed:\n",
+    "\n",
+    "```bash\n",
+    "sudo apt install jupyter\n",
+    "sudo apt install python3-pip\n",
+    "pip install getorg --upgrade\n",
+    "```\n",
+    "\n",
+    "After which you can run this from the `_talks/` directory, via:\n",
+    "\n",
+    "```bash\n",
+    " jupyter nbconvert --to notebook --execute talkmap.ipynb --output talkmap_out.ipynb\n",
+    "```\n",
+    " \n",
+    "The `_talks/` directory contains `.md` files of all your talks. This scrapes the location YAML field from each `.md` file, geolocates it with `geopy/Nominatim`, and uses the `getorg` library to output data, HTML, and Javascript for a standalone cluster map."
    ]
   },
   {
@@ -17,6 +31,7 @@
    },
    "outputs": [],
    "source": [
+    "# Start by installing the dependencies\n",
     "!pip install getorg --upgrade\n",
     "import glob\n",
     "import getorg\n",
@@ -31,6 +46,7 @@
    },
    "outputs": [],
    "source": [
+    "# Collect the Markdown files\n",
     "g = glob.glob(\"*.md\")"
    ]
   },
@@ -42,6 +58,7 @@
    },
    "outputs": [],
    "source": [
+    "# Prepare to geolocate\n",
     "geocoder = Nominatim(user_agent=\"academicpages.github.io\")\n",
     "location_dict = {}\n",
     "location = \"\"\n",
@@ -57,7 +74,7 @@
    },
    "outputs": [],
    "source": [
-    "\n",
+    "# Perform geolocation\n",
     "for file in g:\n",
     "    with open(file, 'r') as f:\n",
     "        lines = f.read()\n",
@@ -80,6 +97,7 @@
    },
    "outputs": [],
    "source": [
+    "# Save the map\n",
     "m = getorg.orgmap.create_map_obj()\n",
     "getorg.orgmap.output_html_cluster_map(location_dict, folder_name=\"../talkmap\", hashed_usernames=False)"
    ]