Merge pull request #296 from laxdog/master

Update / clarify / shorten docs, add missing image from AWS install

docs/contributing/docs.rst

@@ -60,6 +60,12 @@ Then from the ``docs`` directory, build the HTML:
 
      $ make html
 
+If you encounter this error, it's likely that you are running inside a virtual environment.
+
+.. code-block:: console
+
+   Error in "currentmodule" directive:
+
 To get started contributing, you'll want to read the :ref:`reStructuredText
 reference <sphinx:rst-index>`
 

docs/howto/admin/resource-estimation.rst

@@ -16,7 +16,8 @@ installations.
 
 .. math::
 
-    Server Memory Recommended = (Maximum concurrent users \times Maximum memory allowed per user) + 128MB
+    Recommended\, Memory =
+    (Max\, concurrent\, users \times Max\, mem\, per\, user) + 128MB
 
 
 The ``128MB`` is overhead for TLJH and related services. **Server Memory Recommended**
@@ -27,7 +28,7 @@ Maximum concurrent users
 ------------------------
 
 Even if your class has 100 students, most of them will not be using the JupyterHub
-actively at an given moment. At 2am on a normal night, maybe you'll have 10 students
+actively at a single given moment. At 2am on a normal night, maybe you'll have 10 students
 using it. At 2am before a final, maybe you'll have 60 students using it. Maybe
 you'll have a lab session with all 100 of your students using it at the same time.
 
@@ -38,7 +39,7 @@ over time. We generally recommend between 40-60% of your total class size to sta
 Maximum memory allowed per user
 -------------------------------
 
-Depending on what kinda work your users are doing, they will use different amounts
+Depending on what kind of 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. You can use :ref:`howto/admin/nbresuse`
 to determine how much memory your user is using.
@@ -47,7 +48,7 @@ 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 notebook kernel will restart.
+If users use *more* than this alloted amount of memory, their notebook kernel will *restart*.
 
 CPU
 ===
@@ -58,11 +59,13 @@ stop, unlike with RAM.
 
 .. math::
 
-    Server CPU Recommended = (Maximum concurrent users \times Maximum CPU usage per user) + 0.2
+    Recommended\, CPU = (Max\, concurrent\, users \times Max\, CPU\, usage\, per\, user) + 20\%
 
-The ``0.2`` is overhead for TLJH and related services. **Server CPU Recommended**
+The ``20%`` is overhead for TLJH and related services. This is around 20% of a 
-is the amount of CPU the server you acquire should have. We recommend using
+single modern CPU. This, of course, is just an estimate. We recommend using
 the same process used to estimate Memory required for estimating CPU required.
+You cannot use nbresuse for this, but you should carry out normal workflow and
+investigate the CPU usage on the machine.
 
 Disk space
 ==========
@@ -72,7 +75,7 @@ rather than **maximum concurrent** users.
 
 .. math::
 
-    Server Disk Size Recommended = (Total \times Maximum disk usage per user) + 2GB
+    Recommended\, Disk\, Size = (Total\, users \times Max\, disk\, usage\, per\, user) + 2GB
 
 Resizing your server
 ====================

docs/install/amazon.rst

@@ -7,19 +7,19 @@ Installing on Amazon Web Services
 Goal
 ====
 
-By the end of this tutorial, you should have a JupyterHub with some admin
+To have a JupyterHub with admin users and a user environment with conda / pip packages.
-users and a user environment with packages you want installed running on
-`Amazon Web Services <https://aws.amazon.com/>`_.
 
 Prerequisites
 =============
 
-#. An Amazon Web Services account. When you set it up, it will probably ask you 
+#. An Amazon Web Services account.
-   to set your default region. 
 
-   There is a tier of compute use that is free for the first year that is fully
+   The `AWS free tier <https://aws.amazon.com/free/>`_ is fully
    capable of running a minimal littlest Jupyterhub for testing purposes. 
 
+   If asked to choose a default region, choose the one closest to the majority 
+   of your users.
+
 Step 1: Installing The Littlest JupyterHub
 ==========================================
 
@@ -31,9 +31,8 @@ Let's create the server on which we can run JupyterHub.
    
    If you need to adjust your region from your default, there is a drop-down 
    menu between your name and the **Support** menu on the far right of the dark 
-   navigation bar across the top of the window. Adjust the region of the 
+   navigation bar across the top of the window. Adjust the region to match the
-   services you want to interact with now to match the closest one to the 
+   closest one to the majority of your users.
-   majority of your users.
 
 #. On the screen listing all the availabe services, pick **EC2** under **Compute** 
    on the left side at the top of the first column. 
@@ -56,19 +55,19 @@ Let's create the server on which we can run JupyterHub.
       :alt: Click launch instance
    
    This will start the 'launch instance wizard' process.  This lets you customize
-   the kind of server you want, the resources it will have & what it'll be called.
+   the kind of server you want, the resources it will have and its name.
    
    
 #. On the page **Step 1: Choose an Amazon Machine Image (AMI)** you are going 
-   to pick the base image your remote server machine will have. The view will 
+   to pick the base image your remote server will have. The view will 
    default to the 'Quick-start' tab selected and just a few down the page, select 
-   **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type - ami-0ac019f4fcb7cb7e6**.
+   **Ubuntu Server 18.04 LTS (HVM), SSD Volume Type - ami-XXXXXXXXXXXXXXXXX**.
    
    .. image:: ../images/providers/amazon/select_ubuntu_18.png
       :alt: Click Ubuntu server 18.04
    
    The `ami` alpha-numeric at the end references the specific Amazon machine 
-   image. It may be different as Amazon updates these routinely. The 
+   image, ignore this as Amazon updates them routinely. The 
    **Ubuntu Server 18.04 LTS (HVM)** is the important part.
    
    
@@ -84,21 +83,18 @@ Let's create the server on which we can run JupyterHub.
    You may wish to consult the listing `here <https://www.ec2instances.info/>`_ 
    because it shows cost per hour. The **On Demand** price is the pertinent cost.
    
-   (For point of reference, I was able to get a minimal hub that worked for 
+   (For reference, a minimal hub that worked for developing this tutorial used a
-   developing this tutorial using  **t2.micro** tier. That tier is free for 
+   **t2.micro** tier, which is free for Amazon users the first year they sign
-   Amazon users the first year they sign up. Two users were able to concurrently 
+   up. Two users were able to concurrently utilize this development hub without issue.)
-   access this development hub.)
    
-   If you want to **GPUs**, you'll have to scroll down about half way to find 
+   ``GPU graphics`` and ``GPU compute`` products are also available around half way down the page
-   the `GPU graphics` and `GPU compute` products.
    
 #. Under **Step 3: Configure Instance Details**, scroll to the bottom of the page 
-   and toggle the arrow next to **Advanced Details** to get the rest of the page to 
+   and toggle the arrow next to **Advanced Details**. Scroll down to 'User data'. Copy 
-   drop down. Scroll down further to reveal a section entitled 'User data'. Copy 
    the text below, and paste it into the **User data** text box. Replace
    ``<admin-user-name>`` with the name of the first **admin user** for this
    JupyterHub. This admin user can log in after the JupyterHub is set up, and
-   can configure it to their needs. **Remember to add your username**!
+   configure it. **Remember to add your username**!
 
    .. code-block:: bash
 
@@ -112,8 +108,8 @@ Let's create the server on which we can run JupyterHub.
 
    .. note::
 
-      See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
+      See :ref:`topic/installer-actions` for a detailed description and 
-      :ref:`topic/customizing-installer` documents other options that can be passed to the installer.
+      :ref:`topic/customizing-installer` for other options that can be used.
    
 #. Under **Step 4: Add Storage**, you can change the **size** and **type of your 
    disk by adjusting the value in **Size (GiB)** and selecting **Volume Type**.
@@ -121,11 +117,11 @@ Let's create the server on which we can run JupyterHub.
    .. image:: ../images/providers/amazon/change_size_type.png
       :alt: Selecting disk size and type
    
-   Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
+   Check out :ref:`howto/admin/resource-estimation` to help pick
    how much Disk space your server needs.
    
    Hover over the encircled `i` next to **Volume Type** for an explanation of
-   each.  Leaving the default as is is fine. `General Purpose SSD (gp2)` is 
+   each. Leaving the default as is is fine. `General Purpose SSD (gp2)` is 
    recommended for most workloads. With  `Provisioned IOPS SSD (io1)` being the 
    highest-performance SSD volume. Magnetic (standard) is a previous generation 
    volume and not suited for a hub for multi-users.
@@ -150,7 +146,7 @@ Let's create the server on which we can run JupyterHub.
    **Create a new security group**. You should give it a disitnguishing name 
    under **Security group name**
    such as `ssh_web` for future reference. If you have, one from before you can 
-   selectit and adjust it to have the rules you need, if oyu prefer.
+   select it and adjust it to have the rules you need, if you prefer.
    
    The rules will default to include `SSH`. Leave that there, and then click on 
    the **Add Rule** button. Under **Type** for the new rule, change the field 
@@ -186,8 +182,8 @@ Let's create the server on which we can run JupyterHub.
    acknowledge your choice in order to proceed. If you already have a key pair you 
    can select to associate it with this instance, otherwise you need to 
    **Create a new key pair**. Choosing to `Proceed with a key pair` is not 
-   recommended as you'll have no way to access your server if anything goes wrong 
+   recommended as you'll have no way to access your server via SSH if anything
-   with the Jupyterhub amd no way to recover files via download.
+   goes wrong with the Jupyterhub and have no way to recover files via download.
    
    Download and keep the key pair file unless you are associating one you already 
    have.
@@ -244,23 +240,26 @@ Let's create the server on which we can run JupyterHub.
    expecting to see when trying the URL and things work. 
    While waiting until the appropriate time to try, another way to check if 
    things are churning away, is to open the **System Log**. To do this, go to 
-   the **EC2 Management Console** &  highlight the instance by clicking on that 
+   the **EC2 Management Console** & highlight the instance by clicking on that 
    row and then right-click **Instance Settings** > **Get System Log**.
    
    .. image:: ../images/providers/amazon/get_system_log.png
       :alt: Getting system log.
    
-   When the Jupyterhub creation process works and the hub is ready to show you 
+#. When the Jupyterhub creation process finishes and the hub is ready to show 
-   the login the **System Log** will look like the image below if you scroll to 
+   the login, the **System Log** should look similar to the image below. Scroll to 
-   the bottom. Note the line **Starting TLJH installer**. (Somtimes I would 
+   the bottom of your output from the previous step.
-   also see **Started jupyterhub.service** shortly after that, but not always.)
+   Note the line **Starting TLJH installer**, you may also see **Started jupyterhub.service**
+
+   .. image:: ../images/providers/amazon/completed_system_log.png
+      :alt: Completed system log
    
 #. When the installation is complete, it should give you a JupyterHub login page.
    
    .. image:: ../images/first-login.png
       :alt: JupyterHub log-in page
    
-#. Login using the **admin user name** you used in step 6, and a password. Use a
+#. Login using the **admin user name** you used in step 7, and a password. Use a
    strong password & note it down somewhere, since this will be the password for
    the admin user account from now on.
    
@@ -274,4 +273,4 @@ Step 2: Adding more users
 Step 3: Install conda / pip packages for all users
 ==================================================
 
-.. include:: add_packages.txt
+.. include:: add_packages.txt