improve readme file and fix readme variable to avoid overriding a pre…

…viously existing definition

birdhouse/components/cowbird/default.env

@@ -50,10 +50,11 @@ export COWBIRD_LOG_LEVEL=INFO
 # Subdirectory of DATA_PERSIST_SHARED_ROOT containing the user workspaces used by Cowbird
 export USER_WORKSPACES="user_workspaces"
 
-# Override JupyterHub Readme file to use Cowbird's own readme version,
-# which explains the workspace to the user when using Cowbird.
+# Use Cowbird's own readme file, if a readme was not already defined.
+# This file explains the workspace to the user when using Cowbird.
 # Note that the variable can still be overriden by the `env.local` file.
-export JUPYTERHUB_README="$COMPOSE_DIR/components/cowbird/user_workspace_readme.ipynb"
+export JUPYTERHUB_COWBIRD_README="$COMPOSE_DIR/components/cowbird/user_workspace_readme.ipynb"
+export JUPYTERHUB_README="${JUPYTERHUB_README:-${JUPYTERHUB_COWBIRD_README}}"
 
 # Subdirectory containing the hardlinks to the public WPS outputs data
 # This directory will be mounted on the JupyterLab instances and is located by default

birdhouse/components/cowbird/user_workspace_readme.ipynb

@@ -9,6 +9,19 @@
     "\n",
     "This is the user workspace for the JupyterLab environment.\n",
     "\n",
+    "## Home Directory Layout\n",
+    "\n",
+    "```\n",
+    "notebook_dir\n",
+    "├── README.ipynb\n",
+    "├── public\n",
+    "├── tutorial-notebooks\n",
+    "└── writable-workspace\n",
+    "    ├── notebooks\n",
+    "    ├── shapefile_datastore\n",
+    "    └── wps_outputs \n",
+    "```\n",
+    "\n",
     "Here is a description of the different directories found in the workspace :\n",
     "\n",
     "## public\n",
@@ -18,22 +31,27 @@
     "Note that files shared here are read-only.\n",
     "\n",
     "## tutorial-notebooks\n",
+    "\n",
     "This directory contains different notebooks used to showcase different usages of the birdhouse services and shares\n",
-    "step by step instructions of different use cases.\n",
+    "step-by-step instructions of different use cases.\n",
     "These notebooks can be executed but cannot be saved as they are read-only.\n",
     "\n",
     "## writable-workspace\n",
-    "This directory contains different subsdirectories that are customized and specialized to the user.\n",
-    "Note that this space is generally writable for the user, so he can create his own files in this directory as desired.\n",
+    "\n",
+    "This directory contains different subdirectories that are customized and specialized to the user.\n",
+    "Note that this space is generally writable for the user, so they can create their own files in this directory as desired.\n",
     "\n",
     "#### notebooks\n",
+    "\n",
     "This subdirectory is made to contain the different notebooks created by the user.\n",
     "\n",
     "#### shapefile_datastore\n",
+    "\n",
     "This subdirectory is made to contain different files of the shapefile format for Geoserver. Adding new shapefiles to\n",
     "this directory will also automatically publish the shapefile to the user's Geoserver workspace.\n",
     "\n",
     "#### wps_outputs\n",
+    "\n",
     "This read-only directory contains the different WPS outputs user files. Note that this directory might not exist if the\n",
     "user has no user WPS outputs files.\n"
    ]
@@ -65,7 +83,7 @@
     "\n",
     "    This operation is actually supported, but it should be avoided if possible. It will trigger multiple events on\n",
     "    the file system (an update on the parent directory, and a delete followed by a create event on the file), which \n",
-    "    should keep up to date info in GeoServer and Magpie by simply generating new resources. \n",
+    "    should keep up-to-date info in GeoServer and Magpie by simply generating new resources. \n",
     "    \n",
     "    A risk with this is that the delete event will delete the other shapefile files, and the user could lose some \n",
     "    data. It is better to have a copy of the shapefile before applying this operation. Note that renaming one of \n",