From 3ed58fc40cf4f82cf5c850054b8e2547188f53b6 Mon Sep 17 00:00:00 2001
From: yuvipanda <yuvipanda@gmail.com>
Date: Fri, 29 Jun 2018 01:11:21 -0700
Subject: [PATCH] Add guide on picking a notebook interface

---
 docs/guides/notebook-interfaces.rst | 66 +++++++++++++++++++++++++++++
 docs/index.rst                      |  1 +
 docs/troubleshooting/logs.rst       |  2 +
 3 files changed, 69 insertions(+)
 create mode 100644 docs/guides/notebook-interfaces.rst

diff --git a/docs/guides/notebook-interfaces.rst b/docs/guides/notebook-interfaces.rst
new file mode 100644
index 0000000..7d6ccb4
--- /dev/null
+++ b/docs/guides/notebook-interfaces.rst
@@ -0,0 +1,66 @@
+.. _notebook_interfaces:
+
+Notebook Interfaces (Classic, JupyterLab, nteract)
+==================================================
+
+By default, logging into TLJH puts you in the classic Jupyter Notebook interface
+we all know and love. However, there are at least two other popular notebook
+interfaces you can use:
+
+1. `JupyterLab <http://jupyterlab.readthedocs.io/en/stable/>`_
+2. `nteract <https://nteract.io/>`_
+
+Both these interfaces are also shipped with TLJH by default. You can try them
+temporarily, or set them to be the default interface whenever you login.
+
+Trying alternate interface tempoarily
+-------------------------------------
+
+When you log in & start your server, by default the URL in your browser
+will be something like ``/user/<username>/tree``. The ``/tree`` is what tells
+the notebook server to give you the classic notebook interface.
+
+If you change ``/tree`` to ``/lab``, you will get the JupyterLab interface.
+
+If you change ``/tree`` to ``/nteract``, you will get he nteract interface.
+
+You can play around with them and see what fits your use cases best.
+
+Changing default notebook interface
+-----------------------------------
+
+You can change the default interface users get when they log in by modifying
+``config.yaml`` as an admin user.
+
+#. Open the ``config.yaml`` file.
+
+   .. code-block:: bash
+
+      sudo nano /opt/tljh/config.yaml
+
+#. To launch **JupyterLab** when users log in, add the following snippet to the config
+
+   .. code-block:: yaml
+
+      userEnvironment:
+        defaultApp: jupyterlab
+
+#. Alternatively, to launch **nteract** when users log in, add the following snippet to the config
+
+   .. code-block:: yaml
+
+      userEnvironment:
+        defaultApp: nteract
+
+#. Save and exit the editor. With ``nano``, you can do this by pressing ``Ctrl-X``.
+
+#. Apply the changes by restarting JupyterHub. This should not disrupt current users.
+
+   .. code-block:: yaml
+
+      sudo systemctl restart jupyterhub
+
+   If this causes problems, check the :ref:`troubleshoot_logs_jupyterhub` for clues
+   on what went wrong.
+
+Users might have to restart their servers from control panel to get the new interface.
diff --git a/docs/index.rst b/docs/index.rst
index 417ddb9..a3595b2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -42,6 +42,7 @@ Guides provide in-depth explanations of specific topics.
    guides/install
    guides/admin
    guides/user-environment
+   guides/notebook-interfaces
 
 Troubleshooting
 ===============
diff --git a/docs/troubleshooting/logs.rst b/docs/troubleshooting/logs.rst
index 0dcecdc..5f0d0c5 100644
--- a/docs/troubleshooting/logs.rst
+++ b/docs/troubleshooting/logs.rst
@@ -16,6 +16,8 @@ user's notebook server. All the logs are accessible via `journalctl <https://www
    a problem you might have, be careful to redact any private information (such
    as usernames) from the snippet first!
 
+.. _troubleshoot_logs_jupyterhub:
+
 JupyterHub Logs
 ---------------