Merge pull request #91 from jupyterhub/docs

small updates to the docs

docs/howto/resource-estimation.rst

@@ -40,9 +40,16 @@ Maximum memory allowed per user
 
 Depending on what kinda work your users are doing, they will use different amounts
 of memory. The easiest way to determine this is to run through a typical user
-workflow yourself, and measure how much memory is used. Add 20-40% headroom for
-users to 'play around', and that should be the maximum memory allowed per user.
-The system will prevent users from using more memory than this.
+workflow yourself, and measure how much memory is used.
+
+For example, you can begin running a Jupyter Notebook session on your JupyterHub, then open a
+terminal on the JupyterHub and use ``top`` to track how much memory you use
+as you go through the material. A good rule of thumb is to take the maximum amount of memory you used during
+your session, and add 20-40% headroom for users to 'play around'. This is the
+maximum amount of memory that should be given to each user.
+
+If users use *more* than this alloted amount of memory, their kernel will restart (and all
+their progress in the current session will be lost).
 
 CPU
 ===
@@ -56,7 +63,7 @@ stop, unlike with RAM.
     Server CPU Recommended = (Maximum concurrent users \times Maximum CPU usage per user) + 0.2
 
 The ``0.2`` is overhead for TLJH and related services. **Server CPU Recommended**
-is the amount of CPU the server you aquire should have. We recommend using
+is the amount of CPU the server you acquire should have. We recommend using
 the same process used to estimate Memory required for estimating CPU required.
 
 Disk space

docs/index.rst

@@ -3,13 +3,13 @@ The Littlest JupyterHub
 =======================
 
 A simple `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_ distribution for
-a small (0-50) number of users on a single server.
+a small (0-100) number of users on a single server.
 
 Development Status
 ==================
 
 This project is currently in **alpha** state. Most things work, but we might
-still make breaking changes that have no clear upgrade pathway. We are targetting
+still make breaking changes that have no clear upgrade pathway. We are targeting
 a v0.1 release sometime in mid-August 2018. Follow `this milestone <https://github.com/jupyterhub/the-littlest-jupyterhub/milestone/1>`_
 to see progress towards the release!
 
@@ -61,8 +61,12 @@ How-To guides answer the question 'How do I...?' for a lot of topics.
    howto/notebook-interfaces
    howto/resource-estimation
 
+Authentication
+--------------
+
 We have a special set of How-To Guides on using various forms of authentication
-with your JupyterHub.
+with your JupyterHub. For more information on Authentication, see
+:ref:`topic/authenticator-configuration`
 
 .. toctree::
    :titlesonly:

docs/topic/authenticator-configuration.rst

@@ -18,22 +18,32 @@ can be used with TLJH. A number of them ship by default with TLJH:
    their password when they log in for the first time. Default authenticator used in TLJH.
 
 We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
-everything, this guide shows you how to use any authenticator you want by using LDAPAuthenticator as an
-example.
+everything, this guide shows you how to use any authenticator you want with JupyterHub by following
+the authenticator's documentation.
 
-Configuring the authenticator
-=============================
+Setting authenticator properties
+================================
 
-LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
-lists the various configuration options you can set for LDAPAuthenticator. You can set them
-in TLJH with the following pattern:
+JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's
+documentation, you will find these are usually represented as:
+
+.. code-block::
+
+   c.<AuthenticatorName>.<property-name> = <some-value>
+
+You can set these with ``tljh-config`` with:
 
 .. code-block:: bash
 
-   sudo -E tljh-config set auth.<authenticator-name>.<config-option-name> <config-option-value>
+   sudo -E tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
 
-When the documentation asks you to set ``LDAPAuthenticator.server_address`` to some
-value, you can do that with the following command:
+Example
+-------
+
+LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
+lists the various configuration options you can set for LDAPAuthenticator.
+When the documentation asks you to set ``LDAPAuthenticator.server_address``
+to some value, you can do that with the following command:
 
 .. code-block:: bash
 
@@ -45,22 +55,20 @@ enable them. Read the authenticator's documentation carefully for more informati
 Enabling the authenticator
 ==========================
 
-Once you have configured the authenticator as you want, it should be enabled. 
+Once you have configured the authenticator as you want, you should then
+enable it. Usually, the documentation for the authenticator would ask you to add
+something like the following to your ``jupyterhub_config.py`` to enable it:
+
+.. code-block:: python
+
+   c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
+
+You can accomplish the same with ``tljh-config``:
 
 .. code-block:: bash
 
    sudo -E tljh-config set auth.type <fully-qualified-authenticator-name>
 
-For LDAPAuthenticator, the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
-This is the same name that the documentation `asks <https://github.com/jupyterhub/ldapauthenticator#usage>`_
-you to set ``c.JupyterHub.authenticator_class`` to.
-
-For LDAPAuthenticator, this would be:
-
-.. code-block:: bash
-
-   sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
-
 Once enabled, you need to reload JupyterHub for the config to take effect.
 
 .. code-block:: bash
@@ -71,3 +79,14 @@ Try logging in a separate incognito window to check if your configuration works.
 lets you preserve your terminal in case there were errors. If there are
 errors, :ref:`troubleshooting/logs` should help you debug them.
 
+Example
+-------
+
+From the `documentation <https://github.com/jupyterhub/ldapauthenticator#usage>`_ for
+LDAPAuthenticator, we see that the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
+Assuming you have already configured it, the following commands enable LDAPAuthenticator.
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
+   sudo -E tljh-config reload

docs/topic/security.rst

@@ -10,7 +10,7 @@ information about the security model of The Littlest JupyterHub.
 System user accounts
 ====================
 
-Each JupyterHub user gets their own unix user account created when they
+Each JupyterHub user gets their own Unix user account created when they
 first start their server. This protects users from each other, gives them a
 home directory at a well known location, and allows sharing based on file system
 permissions.
@@ -38,8 +38,8 @@ command on the terminal. No password required.
 
 This is a **lot** of power, and they can do pretty much anything they want to
 the server - look at other people's work, modify it, break the server in cool &
-funky ways, etc. This also means if an admin's credentials are compromised (
-easy to guess password, password re-use, etc) the entire JupyterHub is compromised.
+funky ways, etc. This also means **if an admin's credentials are compromised (
+easy to guess password, password re-use, etc) the entire JupyterHub is compromised.**
 
 Off-boarding users securely
 ===========================
@@ -47,9 +47,15 @@ Off-boarding users securely
 When you delete users from the JupyterHub admin console, their unix user accounts
 are **not** removed. This means they might continue to have access to the server
 even after you remove them from JupyterHub. Admins should manually remove the user
-from the server & archive their home directories as needed. If the user removed
-from the server is an admin, extra care must be taken since they could have
-modified the system earlier to continue giving them access.
+from the server & archive their home directories as needed. For example, the
+following command deletes the unix user associated with the JupyterHub user ``yuvipanda``.
+
+.. code-block::
+   sudo userdel jupyter-yuvipanda
+
+If the user removed from the server is an admin, extra care must be taken
+since they could have modified the system earlier to continue giving them
+access.
 
 Per-user ``/tmp``
 =================
@@ -62,6 +68,5 @@ feature of systemd.
 HTTPS
 =====
 
-The Littlest JupyterHub does not currently support HTTPS. Follow `this issue
-<https://github.com/jupyterhub/the-littlest-jupyterhub/issues/29>`_ for progress
-on HTTPS support.
+Any internet-facing JupyterHub should use HTTPS to secure its traffic. For
+information on how to use HTTPS with your JupyterHub, see :ref:`_howto/https`.

docs/tutorials/nbgitpuller.rst

@@ -7,12 +7,12 @@ Distributing materials to users with nbgitpuller
 Goal
 ====
 
-A very common educational need when using JupyterHub for education is to easily
+A very common need when using JupyterHub is to easily
 distribute study materials / lab notebooks to students.
 
 Students should be able to:
 
-1. Easily get latest version of materials, including any updates the instructor
+1. Easily get the latest version of materials, including any updates the instructor
    has made to materials the student already has a copy of.
 2. Be confident they won't lose any of their work. If an instructor has modified
    something the student has also modified, the student's modification should
@@ -109,3 +109,9 @@ Step 2: Users click on the nbgitpuller link
 
 This workflow lets users land directly in the notebook you specified
 without having to understand much about git or the JupyterHub interface.
+
+Advanced: hand-crafting an nbgitpuller link
+===========================================
+
+For information on hand-crafting an ``nbgitpuller`` link, see
+`the nbgitpuller README <https://github.com/jupyterhub/nbgitpuller#constructing-the-nbgitpuller-url>`_.