Merge pull request #364 from kafonek/docs_addition

Docs addition

docs/contributing/plugins.rst

@@ -21,6 +21,11 @@ points in the application that can be explicitly extended by plugins,
 balancing the need to change TLJH internals in the future with the
 stability required for a good plugin ecosystem.
 
+Installing Plugins
+==================
+
+Include ``--plugin <install_name>`` in the Installer script.  See :ref:`topic/customizing-installer` for more info.
+
 Writing a simple plugins
 ========================
 
@@ -126,10 +131,12 @@ If you are looking for a way to extend or customize your TLJH deployment, you mi
 
 Here is a non-exhaustive list of known TLJH plugins:
 
-- `tljh-pangeo <https://github.com/yuvipanda/tljh-pangeo>`_: TLJH Plugin for setting up the Pangeo Stack
+- `tljh-pangeo <https://github.com/yuvipanda/tljh-pangeo>`_: TLJH plugin for setting up the Pangeo Stack
 - `tljh-voila-gallery <https://github.com/voila-dashboards/tljh-voila-gallery>`_: TLJH plugin that installs a gallery of Voilà dashboards
 - `tljh-repo2docker <https://github.com/plasmabio/tljh-repo2docker>`_: TLJH plugin to build multiple user environments with
   `repo2docker <https://repo2docker.readthedocs.io>`_.
+- `tljh-shared-directory <https://github.com/kafonek/tljh-shared-directory>`_: TLJH plugin which sets up a *shared directory*
+   for the Hub users in ``/srv/scratch``.
 
 If you have authored a plugin, please open a PR to add it to this list!
 

docs/howto/content/share-data.rst

@@ -5,7 +5,7 @@ Share data with your users
 ==========================
 
 There are a few options for sharing data with your users, this page covers
-a few useful patterns.
+a few useful patterns.  
 
 Option 1: Distributing data with `nbgitpuller`
 ==============================================
@@ -78,3 +78,62 @@ From now on, when a new user account is created, their home directory will
 have this symbolic link (and any other files in ``/etc/skel``) in their home
 directory. This will have **no effect on the directories of existing
 users**.
+
+Option 3: Create a directory for users to share Notebooks and other files
+=========================================================================
+
+You may want a place for users to share files with each other rather than 
+only having administrators share files with users (Option 2).  In this 
+configuration, any user can put files into ``/srv/scratch`` that other users
+can read. However, only the user that created the file can edit the file.
+
+One way for users to share or "publish" Notebooks in a JupyterHub environment
+is to create a shared directory. Any user can create files in the directory,
+but only the creator may edit that file afterwards.
+
+For instance, in a Hub with three users, User A develops a Notebook in their
+``/home`` directory. When it is ready to share, User A copies it to the
+`shared` directory. At that time, User B and User C can see User A's
+Notebook and run it themselves (or view it in a Dashboard layout
+such as ``voila`` or ``panel`` if that is running in the Hub), but User B
+and User C cannot edit the Notebook. Only User A can make changes.
+
+#. **Log** in to your JupyterHub as an **administrator user**.
+
+#. **Create a terminal session** with your JupyterHub interface.
+
+   .. image:: ../../images/notebook/new-terminal-button.png
+      :alt: New terminal button.
+
+#. **Create a folder** where your data will live. We recommend placing shared
+   data in ``/srv``.  The following command creates a directory ``/srv/scratch``
+
+   .. code-block:: bash
+
+      sudo mkdir -p /srv/scratch
+
+#. **Change group ownership** of the new folder
+
+   .. code-block:: bash
+
+      sudo chown  root:jupyterhub-users /srv/scratch
+
+#. **Change default permissions to use group**.  The default permissions for new
+   sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells
+   new files to use the default permissions for the group ``jupyterhub-users``
+   (``rw-r--r--``)
+
+   .. code-block:: bash
+
+      sudo chmod 777 /srv/scratch
+      sudo chmod g+s /srv/scratch
+
+#. **Create a symbolic link** to the scratch folder in users home directories
+
+   .. code-block:: bash
+
+      sudo ln -s /srv/scratch /etc/skel/scratch
+
+.. note::
+   The TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above.
+   Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script to install it.