add info on notebook extensions

docs/howto/admin/enable-extensions.rst

@@ -0,0 +1,60 @@
+.. _howto/admin/extensions:
+
+====================================
+Enabling Jupyter Notebook extensions
+====================================
+
+Jupyter contributed notebook 
+`extensions <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/index.html>`_ are
+community-contributed and maintained plug-ins to the Jupyter notebook. These extensions
+serve many purposes, from `pedagogical tools <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/codefolding/readme.html>`_
+to tools for `converting <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/latex_envs/README.html>`_
+and `editing <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/spellchecker/README.html>`_
+notebooks.
+
+Extensions are often added and enabled through the graphical user interface of the notebook.
+However, this interface only makes the extension available to the user, not all users on a 
+hub. Instead, to make contributed extensions available to your users, you will use the command 
+line. This can be completed using the terminal in the JupyterHub (or via SSH-ing into your 
+VM and using this terminal).
+
+.. _tljh_extension_cli:
+
+Enabling extensions via the command line 
+========================================
+
+#. There are `multiple ways <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/install.html>`_
+   to install contributed extensions. For this example, we will use ``pip``.
+
+   .. code-block:: bash
+
+      sudo -E pip install jupyter_contrib_nbextensions
+
+#. Next, add the notebook extension style files to the Jupyter configuration files.
+
+   .. code-block:: bash
+
+      sudo -E jupyter contrib nbextension install --system
+
+#. Then, you will enable the extensions you would like to use. The syntax for this is 
+   ``jupyter nbextension enable`` followed by the path to the desired extension's main file. 
+   For example, to enable `scratchpad <https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/scratchpad/README.html>`_,
+   you would type the following: 
+
+   .. code-block:: bash
+
+      sudo -E jupyter nbextension enable scratchpad/main --system
+
+#. When this is completed, the enabled extension should be visible in the extension list:
+
+   .. code-block:: bash
+
+      jupyter nbextension list
+
+#. You can also verify the availability of the extension via its user interface in the notebook.
+   For example, spellchecker adds an ABC checkmark icon to the interface.
+
+   .. image:: ../../images/admin/enable-spellcheck.png
+      :alt: spellcheck-interface-changes
+
+

docs/howto/admin/resize.rst

@@ -1,15 +1,21 @@
 .. _howto/admin/resize:
 
-=================
+=================================================
-Resizing a server
+Resize the resources available to your JupyterHub 
-=================
+=================================================
 
-As you are using your JupyterHub, you may find that you have a need to increase or decrease 
+As you are using your JupyterHub, you may need to increase or decrease 
-the amount of resources allocated to your TLJH install. How resources can be reallocated 
+the amount of resources allocated to your TLJH install. The kinds of resources that can be
-will depend on the server interface; consult the installation page for your provider for 
+allocated, as well as the process to do so, will depend on the provider / interface for your
-more information. 
+VM. We recommend consulting the installation page for your provider for more information. This
+page covers the steps your should take on your JupyterHub *after* you've reallocated resources on
+the cloud provider of your choice.
 
-However, once resources have been reallocated, you must tell TLJH to make use of these resources,
+Currently there are instructions to resize your resources on the following providers:
+
+* :ref:`Digital Ocean <digitalocean/resize>`.
+
+Once resources have been reallocated, you must tell TLJH to make use of these resources,
 and verify that the resources have become available.
 
 .. _tljh_verify:
@@ -17,11 +23,10 @@ and verify that the resources have become available.
 Verifying a Resize 
 ==================
 
-#. Once you have resized your server, you will need to tell the JupyterHub to make use of 
+#. Once you have resized your server, tell the JupyterHub to make use of 
-   these new resources. To accomplish this, you will follow the instructions in 
+   these new resources. To accomplish this, follow the instructions in 
-   :ref:`topic/tljh-config` to edit :ref:`tljh-set-user-limits`, and 
+   :ref:`topic/tljh-config` to set new memory or CPU limits and reload the hub. This can be completed 
-   reload the hub. These steps can be completed using the terminal in the JupyterHub. 
+   using the terminal in the JupyterHub (or via SSH-ing into your VM and using this terminal).
-   They can also be completed through the terminal.
 
 #. TLJH configuration options can be verified by viewing the tljh-config output.
 
@@ -29,28 +34,29 @@ Verifying a Resize
 
       sudo tljh-config show
 
+   Double-check that your changes are reflected in the output.
 
-#. If you have changed your memory availability successfully, this will be reflected 
+#. **To verify changes to memory**, confirm that it worked by starting
-   in the `nbresuse <https://github.com/yuvipanda/nbresuse>`_ extension in the upper-right 
+   a new server (if you had one previously running, click "Control Panel -> Stop My Server" to
-   when you open a Jupyter notebook on the Hub.
+   shut down your active server first), opening a notebook, and checking the value of the 
+   `nbresuse <https://github.com/yuvipanda/nbresuse>`_ extension in the upper-right.
 
    .. image:: ../../images/nbresuse.png
       :alt: nbresuse demonstration
 
-#. If you have changed the number of cores, this can be verified at the command line. 
+#. **To verify changes to CPU**, use the ``nproc`` from a terminal. 
-   ``nproc`` displays the number of available cores, and should be equal to the 
+   This command displays the number of available cores, and should be equal to the 
    number of cores you selected in your provider's interface.
 
    .. code-block:: bash
 
       nproc --all
 
-
+#. **To verify currently-available disk space**, use the ``df`` command in a terminal. This shows
-#. Disk space changes can be verified, as well. The ``df`` command shows how much disk 
+   how much disk space is available. The ``-hT`` argument allows us to have this printed in a human readable
-   space is available. The ``-hT`` argument allows us to have this printed in a human readable
+   format, and condenses the output to show one storage volume. Note that currently you cannot
-   format, and condenses the output to show one storage volume. 
+   change the disk space on a per-user basis.
 
    .. code-block:: bash
 
       df -hT /home
-

docs/howto/env/server-resources.rst

@@ -0,0 +1,10 @@
+.. _howto/env/server-resources:
+
+======================================
+Configure resources available to users
+======================================
+
+To configure the resources that are available to your users (such as RAM, CPU
+and Disk Space), see the section :ref:`tljh-set-user-limits`. For information
+on **resizing** the environment available to users *after* you've created your
+JupyterHub, see :ref:`howto/admin/resize`.

docs/index.rst

@@ -58,6 +58,7 @@ The user environment
 
    howto/env/user-environment
    howto/env/notebook-interfaces
+   howto/env/server-resources
 
 Authentication
 --------------
@@ -84,6 +85,8 @@ Administration and security
    howto/admin/resize
    howto/admin/nbresuse
    howto/admin/https
+   howto/admin/enable-extensions
+
 
 Topic Guides
 ============

docs/install/digitalocean.rst

@@ -118,16 +118,38 @@ Step 3: Install conda / pip packages for all users
 
 .. include:: add_packages.txt
 
+.. _digitalocean/resize:
+
 Step 4: Resizing and editing the droplet
 ========================================
 
-#. As you are using your JupyterHub, you may find that you need more memory, 
+As you use your JupyterHub, you may find that you need more memory, 
-   disk space, or CPUs. Digital Ocean servers can be resized in the 
+disk space, or CPUs. Digital Ocean servers can be resized in the 
-   "Resize Droplet" panel.
+"Resize Droplet" panel. These instructions take you through the process.
+
+#. First, click on the name of your newly-created
+   Droplet to enter its configuration page.
+
+#. Next, **turn off your Droplet**. This allows DigitalOcean to make
+   modifications to your VM. This will shut down your JupyterHub (temporarily).
+
+   .. image:: ../images/providers/digitalocean/power-off.png
+      :alt: Power off your Droplet
+      :width: 200px
+
+#. Once your Droplet has been turned off, click "Resize",
+   which will take you to a menu with options to resize your VM.
 
    .. image:: ../images/providers/digitalocean/resize-droplet.png
       :alt: Resize panel of digital ocean
 
-   Further information on making more resources available to TLJH and verifying resource 
+#. Decide what kinds of resources you'd like to resize, then click on a new VM
-   availability can be found in the How-To :ref:`howto/admin/resize`. 
+   type in the list below. Finally, click "Resize". This may take a few moments!
+
+#. Once your Droplet is resized, **turn your Droplet back on**. This makes your JupyterHub
+   available to the world once again. This will take a few moments to complete.
+
+Now that you've resized your Droplet, you may want to change the resources available
+to your users. Further information on making more resources available to
+users and verifying resource availability can be found in :ref:`howto/admin/resize`.