Merge pull request #123 from choldgraf/docsupdate

[MRG] updating content from zexuan's user test

docs/_static/custom.css

@@ -0,0 +1,3 @@
+div.sphinxsidebarwrapper h1.logo {
+  font-size: 2.3rem;
+}

docs/doc-requirements.txt

@@ -0,0 +1 @@
+sphinx_copybutton

docs/howto/admin-users.rst

@@ -1,55 +0,0 @@
-.. _howto/admin-users:
-
-========================
-Add / Remove admin users
-========================
-
-Admin users in TLJH have the following powers:
-
-#. Full root access to the server with passwordless ``sudo``.
-   This lets them do literally whatever they want in the server
-#. Access servers / home directories of all other users
-#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
-#. Change configuration of TLJH
-
-This is a lot of power, so make sure you know who you are giving it
-to. Admin users should have decent passwords / secure logni mechanisms,
-so attackers can not easily gain control of the system.
-
-Make sure an admin user is present
-==================================
-
-You should make sure an admin user is present when you **install** TLJH
-the very first time. The ``:ref:`--admin <topic/customizing-installer/admin>```
-flag passed to the installer does this. If you had forgotten to do so, the
-easiest way to fix this is to run the installer again.
-
-Adding new admin users
-======================
-
-New admin users can be added by executing the following commands on an
-admin terminal:
-
-.. code-block:: bash
-
-   sudo -E tljh-config add-item users.admin <username>
-   sudo -E tljh-config reload
-
-If the user is already using the JupyterHub, they might have to stop and
-start their server from the control panel to gain new powers.
-
-Removing admin users
-====================
-
-You can remove an existing admin user by executing the following commands in
-an admin terminal:
-
-.. code-block:: bash
-
-   sudo -E tljh-config remove-item users.admin <username>
-   sudo -E tljh-config reload
-
-If the user is already using the JupyterHub, they will continue to have
-some of their admin powers until their server is stopped. Another admin
-can force their server to stop by clicking 'Stop Server' in the admin
-panel.

docs/howto/admin/admin-users.rst

@@ -0,0 +1,101 @@
+.. _howto/admin/admin-users:
+
+========================
+Add / Remove admin users
+========================
+
+Admin users in TLJH have the following powers:
+
+#. Full root access to the server with passwordless ``sudo``.
+   This lets them do literally whatever they want in the server
+#. Access servers / home directories of all other users
+#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
+#. Change configuration of TLJH
+
+This is a lot of power, so make sure you know who you are giving it
+to. Admin users should have decent passwords / secure logni mechanisms,
+so attackers can not easily gain control of the system.
+
+.. important::
+
+   You should make sure an admin user is present when you **install** TLJH
+   the very first time. The ``:ref:`--admin <topic/customizing-installer/admin>```
+   flag passed to the installer does this. If you had forgotten to do so, the
+   easiest way to fix this is to run the installer again.
+
+Adding admin users from the JupyterHub interface
+================================================
+
+There are two primary user interfaces for doing work on your JupyterHub. By
+default, this is the Notebook Interface, and will be used in this section.
+If you are using JupyterLab, you can access the Notebook Interface by replacing
+``/lab`` with ``/tree`` in your URL.
+
+#. First, navigate to the Jupyter Notebook interface home page. You can do this
+   by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
+
+#. Open the **Control Panel** by clicking the control panel button on the top
+   right of your JupyterHub.
+
+   .. image:: ../../images/control-panel-button.png
+      :alt: Control panel button in notebook, top right
+
+#. In the control panel, open the **Admin** link in the top left.
+
+   .. image:: ../../images/admin/admin-access-button.png
+      :alt: Admin button in control panel, top left
+
+   This opens up the JupyterHub admin page, where you can add / delete users,
+   start / stop peoples' servers and see who is online.
+
+#. Click the **Add Users** button.
+
+   .. image:: ../../images/admin/add-users-button.png
+      :alt: Add Users button in the admin page
+
+   A **Add Users** dialog box opens up.
+
+#. Type the names of users you want to add to this JupyterHub in the dialog box,
+   one per line. **Make sure to tick the Admin checkbox**.
+
+   .. image:: ../../images/admin/add-users-dialog.png
+      :alt: Adding users with add users dialog
+
+#. Click the **Add Users** button in the dialog box. Your users are now added
+   to the JupyterHub with administrator privileges!
+
+Adding admin users from the command line
+========================================
+
+Sometimes it is easier to add or remove admin users from the command line (for
+example, if you forgot to add an admin user when first setting up your JupyterHub).
+
+Adding new admin users
+----------------------
+
+New admin users can be added by executing the following commands on an
+admin terminal:
+
+.. code-block:: bash
+
+   sudo -E tljh-config add-item users.admin <username>
+   sudo -E tljh-config reload
+
+If the user is already using the JupyterHub, they might have to stop and
+start their server from the control panel to gain new powers.
+
+Removing admin users
+--------------------
+
+You can remove an existing admin user by executing the following commands in
+an admin terminal:
+
+.. code-block:: bash
+
+   sudo -E tljh-config remove-item users.admin <username>
+   sudo -E tljh-config reload
+
+If the user is already using the JupyterHub, they will continue to have
+some of their admin powers until their server is stopped. Another admin
+can force their server to stop by clicking 'Stop Server' in the admin
+panel.

docs/howto/admin/https.rst

@@ -1,4 +1,4 @@
-.. _howto/https:
+.. _howto/admin/https:
 
 ============
 Enable HTTPS

docs/howto/admin/nbresuse.rst

@@ -1,4 +1,4 @@
-.. _howto/nbresuse:
+.. _howto/admin/nbresuse:
 
 =======================
 Check your memory usage
@@ -11,5 +11,5 @@ top right corner of the notebook interface. Note that this is memory usage
 for everything your user is running through the Jupyter notebook interface,
 not just the specific notebook it is shown on.
 
-.. image:: ../images/nbresuse.png
+.. image:: ../../images/nbresuse.png
    :alt: Memory limit / usage shown with nbresuse

docs/howto/admin/resource-estimation.rst

@@ -1,4 +1,4 @@
-.. _howto/resource-estimation:
+.. _howto/admin/resource-estimation:
 
 ===================================
 Estimate Memory / CPU / Disk needed
@@ -40,7 +40,7 @@ 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. You can use :ref:`howto/nbresuse`
+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.
 
 A good rule of thumb is to take the maximum amount of memory you used during

docs/howto/auth/firstuse.rst

@@ -0,0 +1,36 @@
+.. _howto/auth/firstuse:
+
+==================================================
+Let users choose a password when they first log in
+==================================================
+
+The **First Use Authenticator** lets users choose their own password.
+Upon their first log-in attempt, whatever password they use will be stored
+as their password for subsequent log in attempts. This is
+the default authenticator that ships with TLJH.
+
+Enabling the authenticator
+==========================
+
+.. note:: the FirstUseAuthenticator is enabled by default in TLJH.
+
+#. Enable the authenticator and reload config to apply the configuration:
+
+   sudo -E tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
+   sudo -E tljh-config reload
+
+Users who are currently logged in will continue to be logged in. When they
+log out and try to log back in, they will be asked to provide a username and
+password.
+
+Allowing anyone to log in to your JupyterHub
+============================================
+
+By default, you need to manually create user accounts before they will be able
+to log in to your JupyterHub. If you wish to allow **any** user to access
+the JupyterHub, run the following command.
+
+.. code-block:: bash
+
+   tljh-config set auth.FirstUseAuthenticator.create_users true
+   tljh-config reload

docs/howto/auth/github.rst

@@ -9,52 +9,81 @@ GitHub user ID / password. To do so, you'll first need to register an
 application with GitHub, and then provide information about this
 application to your ``tljh`` configuration.
 
-Enabling the authenticator
-==========================
-
 .. note::
 
    You'll need a GitHub account in order to complete these steps.
 
-#. Create a GitHub application
-   #. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
-   #. **Application name**: Choose a descriptive application name (e.g. ``tljh``)
-   #. **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
-   #. **Application description**: Use any description that you like.
-   #. **Authorization callback URL**: Insert text with the following form::
+Step 1: Create a GitHub application
+===================================
 
-      http://<my-tljh-url>/hub/oauth_callback
+#. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
 
-   #. When you're done filling in the page, it should look something like this:
+   * **Application name**: Choose a descriptive application name (e.g. ``tljh``)
+   * **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
+   * **Application description**: Use any description that you like.
+   * **Authorization callback URL**: Insert text with the following form::
+
+          http://<my-tljh-ip-address>/hub/oauth_callback
+
+   * When you're done filling in the page, it should look something like this:
 
       .. image:: ../../images/auth/github/create_application.png
          :alt: Create a GitHub OAuth application
-   #. Click "Register application".
-   #. You'll be taken to a page with the registered application details. Note
-      the **Client ID** and **Client Secret**, as you will use these later.
+#. Click "Register application". You'll be taken to a page with the registered application details.
+#. Copy the **Client ID** and **Client Secret** from the application details
+   page. You will use these later to configure your JupyterHub authenticator.
 
-      .. image:: ../../images/auth/github/client_id_secret.png
-        :alt: Your client ID and secret
+   .. image:: ../../images/auth/github/client_id_secret.png
+     :alt: Your client ID and secret
 
-#. Configure your JupyterHub to use the GitHub Oathenticator
-   #. Log in as an administrator account to your JupyterHub.
-   #. Open a terminal on your JupyterHub.
-   #. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands::
+.. important::
 
-        sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
-        sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
+   If you are using a virtual machine from a cloud provider and
+   **stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
+   IP address** to it. In this case, **you must update your GitHub application information**
+   with the new IP address.
 
-   #. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
+Configure your JupyterHub to use the GitHub Oauthenticator
+==========================================================
 
-        sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
+We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
+For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
 
-   #. Restart your JupyterHub so that new users see these changes::
+#. Log in as an administrator account to your JupyterHub.
+#. Open a terminal window.
 
-        sudo -E tljh-config reload
-#. Confirm that the new authentactor works.
-   #. Open an **incognito window** in your browser.
-   #. Go to your JupyterHub URL.
-   #. You should see a GitHub login button like below:
+   .. image:: ../../images/notebook/new-terminal-button.png
+      :alt: New terminal button.
 
-      .. image:: ../../images/auth/github/client_id_secret.png
-         :alt: The GitHub authenticator login button.
+#. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands::
+
+     sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
+
+   ::
+
+     sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
+
+#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
+
+     sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
+
+#. Restart your JupyterHub so that new users see these changes::
+
+     sudo -E tljh-config reload
+
+Confirm that the new authentactor works
+=======================================
+
+#. **Open an incognito window** in your browser (do not log out until you confirm
+   that the new authentication method works!)
+#. Go to your JupyterHub URL.
+#. You should see a GitHub login button like below:
+
+   .. image:: ../../images/auth/github/login_button.png
+      :alt: The GitHub authenticator login button.
+
+#. After you log in with your GitHub credentials, you should be directed to the
+   Jupyter interface used in this JupyterHub.
+
+#. **If this does not work** you can revert back to the default
+   JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`.

docs/howto/content/add-data.rst

@@ -0,0 +1,95 @@
+.. _howto/content/add-data:
+
+=============================
+Adding data to the JupyterHub
+=============================
+
+This section covers how to add data to your JupyterHub either from the internet
+or from your own machine. To learn how to **share data** that is already
+on your JupyterHub, see :ref:`howto/content/share-data`.
+
+.. note::
+
+   When you add data using the methods on this page, you will **only add it
+   to your user directory**. This is not a place that is accessible to others.
+   For information on sharing this data with users on the JupyterHub, see
+   :ref:`howto/content/share-data`.
+
+Adding data from your local machine
+===================================
+
+The easiest way to add data to your JupyterHub is to use the "Upload" user
+interface. To do so, follow these steps:
+
+#. First, navigate to the Jupyter Notebook interface home page. You can do this
+   by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
+#. Click the "Upload" button to open the file chooser window.
+
+   .. image:: ../../images/content/upload-button.png
+      :alt: The upload button in Jupyter.
+#. Choose the file you wish to upload. You may select multiple files if you
+   wish.
+#. Click "Upload" for each file that you wish to upload.
+
+   .. image:: ../../images/content/file-upload-buttons.png
+      :alt: Multiple file upload buttons.
+#. Wait for the progress bar to finish for each file. These files will now
+   be on your JupyterHub, your home user's home directory.
+
+To learn how to **share** this data with new users on the JupyterHub,
+see :ref:`howto/content/share-data`.
+
+Downloading data from the command line
+======================================
+
+If the data of interest is on the internet, you may also use code in order
+to download it to your JupyterHub. There are several ways of doing this, so
+we'll cover the simplest approach using the unix tool ``wget``.
+
+#. Log in to your JupyterHub and open a terminal window.
+
+   .. image:: ../../images/notebook/new-terminal-button.png
+      :alt: New terminal button.
+
+#. Use ``wget`` to download the file to your current directory in the terminal.
+
+   .. code-block:: bash
+
+      wget <MY-FILE-URL>
+
+Example: Downloading the `gapminder <https://www.gapminder.org/>`_ dataset.
+---------------------------------------------------------------------------
+
+In this example we'll download the `gapminder <https://www.gapminder.org/>`_
+dataset, which contains information about country GDP and live expectancy over
+time. You can download it from your browser `at this link <https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip>`_.
+
+#. Log in to your JupyterHub and open a terminal window.
+
+   .. image:: ../../images/notebook/new-terminal-button.png
+      :alt: New terminal button.
+
+#. Use ``wget`` to download the gapminder dataset to your current directory in
+   the terminal.
+
+   .. code-block:: bash
+
+      wget https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip
+
+#. This is a **zip** file, so we'll need to download a unix tool called "unzip"
+   in order to unzip it.
+
+   .. code-block:: bash
+
+      sudo -E apt-get install unzip
+
+#. Finally, unzip the the file:
+
+   unzip python-novice-gapminder-data.zip
+
+#. Confirm that your data was unzipped. It could be in a folder called ``data/``.
+
+To learn how to **share** this data with new users on the JupyterHub,
+see :ref:`howto/content/share-data`.
+
+.. TODO: Downloading data with the "download" module in Python? https://github.com/choldgraf/download

docs/howto/content/nbgitpuller.rst

@@ -1,4 +1,4 @@
-.. _tutorials/nbgitpuller:
+.. _howto/content/nbgitpuller:
 
 ================================================
 Distributing materials to users with nbgitpuller
@@ -38,22 +38,24 @@ Pre-requisites
 Step 1: Generate nbgitpuller link
 =================================
 
+**Generate the link with a Binder app**.
+
 #. The easiest way to generate an nbgitpuller link is to use the
    `mybinder.org based application <https://mybinder.org/v2/gh/jupyterhub/nbgitpuller/master?urlpath=apps/binder%2Flink_generator.ipynb>`_.
    Open it, and wait for it to load.
 
-   .. image:: ../images/nbgitpuller/binder-progress.png
+   .. image:: ../../images/nbgitpuller/binder-progress.png
       :alt: Progress bar as the binder application loads
 
 #. A blank form with some help text will open up.
 
-   .. image:: ../images/nbgitpuller/blank-application.png
+   .. image:: ../../images/nbgitpuller/blank-application.png
       :alt: Blank application to make nbgitpuller links
 
-#. Enter the URL to your hub under ``hub_url``. Include ``http://`` or
-   ``https://`` as appropriate.
+#. Enter the IP address or URL to your JupyterHub under ``hub_url``.
+   Include ``http://`` or ``https://`` as appropriate.
 
-   .. image:: ../images/nbgitpuller/hub-url-application.png
+   .. image:: ../../images/nbgitpuller/hub-url-application.png
       :alt: Application with hub_url filled out
 
 #. Enter the URL to your Git repository. This could be from GitHub,
@@ -62,7 +64,7 @@ Step 1: Generate nbgitpuller link
    typing the URL here, you'll notice that the link is already
    being printed below!
 
-   .. image:: ../images/nbgitpuller/git-url-application.png
+   .. image:: ../../images/nbgitpuller/git-url-application.png
       :alt: Application with git_url filled out
 
 #. If your git repository is using a non-default branch name,
@@ -74,7 +76,7 @@ Step 1: Generate nbgitpuller link
    Make sure this file exists, otherwise users will get a 'File not found'
    error.
 
-   .. image:: ../images/nbgitpuller/filepath-application.png
+   .. image:: ../../images/nbgitpuller/filepath-application.png
       :alt: Application with filepath filled out
 
    If you do not specify a file path, the user will be shown the
@@ -88,6 +90,25 @@ The link printed at the bottom of the form can be distributed to students
 now! You can also click it to test that it is working as intended,
 and adjust the form values until you get something you are happy with.
 
+**Hand-craft your nbgitpuller link**
+
+If you'd prefer to hand-craft your ``nbgitpuller`` link (e.g. if the Binder
+link above doesn't work), you can use the following pattern::
+
+   http://<my-jhub-address>/hub/user-redirect/git-pull?repo=<your-repo-url>&branch=<your-branch-name>&subPath=<subPath>&app=<notebook | lab>
+
+- **repo** is the URL of the git repository you want to clone. This parameter is required.
+- **branch** is the branch name to use when cloning from the repository.
+  This parameter is optional and defaults to ``master``.
+- **subPath** is the path of the directory / notebook inside the repo to launch after cloning.
+  This parameter is optional, and defaults to opening the base directory of the linked Git repository.
+- **app** This parameter is optional and defaults to either the environment variable
+  `NBGITPULLER_APP`'s value or `notebook` if it is undefined. The allowed values
+  are `lab` and `notebook`, the value will determine in what application view
+  you end up in.
+- **urlPath** will, if specified, override `app` and `subPath` and redirect
+  blindly to the specified path.
+
 Step 2: Users click on the nbgitpuller link
 ===========================================
 
@@ -102,7 +123,7 @@ Step 2: Users click on the nbgitpuller link
 #. Users will see a progress bar as the git repository is fetched & any
    automatic merging required is performed.
 
-   .. image:: ../images/nbgitpuller/pull-progress.png
+   .. image:: ../../images/nbgitpuller/pull-progress.png
       :alt: Progress bar with git repository being pulled
 
 #. Users will now be redirected to the notebook specified in the URL!

docs/howto/content/share-data.rst

@@ -0,0 +1,80 @@
+.. _howto/content/share-data:
+
+==========================
+Share data with your users
+==========================
+
+There are a few options for sharing data with your users, this page covers
+a few useful patterns.
+
+Option 1: Distributing data with `nbgitpuller`
+==============================================
+
+For small datasets, the simplest way to share data with your users is via
+``nbgitpuller`` links. In this case, users click on your link and the dataset
+contained in the link's target repository is downloaded to the user's home
+directory. Note that a copy of the dataset will be made for each user.
+
+For information on creating and sharing ``nbgitpuller`` links, see
+:ref:`howto/content/nbgitpuller`.
+
+Option 2: Create a read-only shared folder for data
+===================================================
+
+If your data is large or you don't want copies of it to exist, you can create
+a read-only shared folder that users have access to. To do this, follow these
+steps:
+
+#. **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 two folders (``/srv/data`` and
+   ``/srv/data/my_shared_data_folder``).
+
+   .. code-block:: bash
+
+      sudo -E mkdir -p /srv/data/my_shared_data_folder
+
+#. **Download the data** into this folder. See :ref:`howto/content/add-data` for
+   details on how to do this.
+
+#. All users now have read access to the data in this folder.
+
+Add a link to the shared folder in the user home directory
+----------------------------------------------------------
+
+Optionally, you may also **create a symbolic link to the shared data folder**
+that you created above in each **new user's** home directory.
+
+To do this, you can use the server's **user skeleton directory** (``/etc/skel``).
+Anything that is placed in this directory will also
+show up in a new user's home directory.
+
+To create a link to the shared folder in the user skeleton directory,
+follow these steps:
+
+#. ``cd`` into the skeleton directory:
+
+   .. code-block:: bash
+
+      cd /etc/skel
+
+#. **Create a symbolic link** to the data folder
+
+   .. code-block:: bash
+
+      sudo ln -s /src/data/my_shared_data_folder my_shared_data_folder
+
+#. **Confirm that this worked** by logging in as a new user. You can do this
+   by opening a new "incognito" browser window and accessing your JupyterHub.
+   After you log in as a **new user**, the folder should appear in your new
+   user home directory.
+
+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**.

docs/howto/env/notebook-interfaces.rst

@@ -1,8 +1,8 @@
-.. _notebook_interfaces:
+.. _howto/env/notebook_interfaces:
 
-===========================================
-Change default Notebook Interface for users
-===========================================
+=======================================
+Change default User Interface for users
+=======================================
 
 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
@@ -14,8 +14,8 @@ interfaces you can use:
 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
-=====================================
+Trying an alternate interface temporarily
+=========================================
 
 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

docs/howto/env/user-environment.rst

@@ -1,4 +1,4 @@
-.. _user_environment:
+.. _howto/env/user_environment:
 
 ==================================
 Install conda, pip or apt packages
@@ -6,10 +6,10 @@ Install conda, pip or apt packages
 
 :abbr:`TLJH (The Littlest JupyterHub)` starts all users in the same `conda <https://conda.io/docs/>`_
 environment. Packages / libraries installed in this environment are available
-to all users on the JupyterHub. Users with :ref:`admin rights <howto/admin-users>` can install packages
+to all users on the JupyterHub. Users with :ref:`admin rights <howto/admin/admin-users>` can install packages
 easily.
 
-.. _user_environment_pip:
+.. _howto/env/user_environment_pip:
 
 Installing pip packages
 =======================
@@ -20,7 +20,7 @@ almost 145,000 packages in it right now, so a lot of what you need is going to b
 
 1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
 
-   .. image:: ../images/notebook/new-terminal-button.png
+   .. image:: ../../images/notebook/new-terminal-button.png
       :alt: New Terminal button under New menu
 
    If you already have a terminal open as an admin user, that should work too!
@@ -39,7 +39,7 @@ almost 145,000 packages in it right now, so a lot of what you need is going to b
       If you get an error message like ``sudo: pip: command not found``,
       make sure you are not missing the ``-E`` parameter after ``sudo``.
 
-.. _user_environment_conda:
+.. _howto/env/user_environment_conda:
 
 Installing conda packages
 =========================
@@ -54,7 +54,7 @@ a community maintained repository of  conda packages.
 
 1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
 
-   .. image:: ../images/notebook/new-terminal-button.png
+   .. image:: ../../images/notebook/new-terminal-button.png
       :alt: New Terminal button under New menu
 
    If you already have a terminal open as an admin user, that should work too!
@@ -73,7 +73,7 @@ a community maintained repository of  conda packages.
       If you get an error message like ``sudo: conda: command not found``,
       make sure you are not missing the ``-E`` parameter after ``sudo``.
 
-.. _user_environment_apt:
+.. _howto/env/user_environment_apt:
 
 Installing apt packages
 =======================
@@ -90,7 +90,7 @@ make sure to look in the version of Ubuntu you are using!
 
 1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
 
-   .. image:: ../images/notebook/new-terminal-button.png
+   .. image:: ../../images/notebook/new-terminal-button.png
       :alt: New Terminal button under New menu
 
    If you already have a terminal open as an admin user, that should work too!

docs/howto/share-data.rst

@@ -1,62 +0,0 @@
-.. _howto/share-data:
-
-==========================
-Share data with your users
-==========================
-
-There are a few options for sharing data with your users, this page covers
-a few useful patterns.
-
-Distributing data with `nbgitpuller`
-====================================
-
-For small datasets, the simplest way to share data with your users is via
-``nbgitpuller`` links. In this case, users click on your link and the dataset
-contained in the link's target repository is downloaded to the user's home
-directory. Note that a copy of the dataset will be made for each user.
-
-For information on creating and sharing ``nbgitpuller`` links, see
-:ref:`tutorials/nbgitpuller`.
-
-Distributing data with a read-only shared folder
-================================================
-
-If your data is large or you don't want copies of it to exist, you can create
-a read-only shared folder that users have access to. To do this, follow these
-steps:
-
-#. Log in to your JupyterHub as an **administrator user**.
-#. Create a terminal session within your JupyterHub interface.
-#. Create a folder where your data will live:
-
-   .. code-block:: bash
-
-      sudo mkdir /srv/data/mydatafolder
-
-#. Download the data into this folder. For example, using ``sudo curl`` or by running
-   a ``python`` script that downloads the data.
-
-#. All users now have read access to the data in this folder.
-
-Optionally, you may also **create a symbolic link to the data folder** in each
-**new user's** home directory. To do this, you can use the server's "user skeleton"
-directory (``/etc/skel``). Anything that is placed in this directory will also
-show up in a new user's home directory. To create a link to the dataset,
-follow these steps:
-
-#. Change into the skeleton directory:
-
-   .. code-block:: bash
-
-      cd /etc/skel
-
-#. Create a symbolic link to the data folder
-
-   .. code-block:: bash
-
-      sudo ln -s /src/data/mydatafolder mydatafolder
-
-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 effects on the home directories of existing
-users.

docs/index.rst

@@ -33,33 +33,31 @@ Ubuntu 18.04. We have a bunch of tutorials to get you started.
      install/custom-server
 
 Once you are ready to run your server for real,
-it's a good idea to proceed directly to :doc:`howto/https`.
-
-Tutorials
-=========
-
-Tutorials guide you step-by-step through accomplishing a specific task.
-
-.. toctree::
-   :titlesonly:
-
-   tutorials/nbgitpuller.rst
+it's a good idea to proceed directly to :doc:`howto/admin/https`.
 
 How-To Guides
 =============
 
 How-To guides answer the question 'How do I...?' for a lot of topics.
 
+Content and Data
+----------------
+
 .. toctree::
    :titlesonly:
 
-   howto/https
-   howto/user-environment
-   howto/admin-users
-   howto/share-data
-   howto/notebook-interfaces
-   howto/resource-estimation
-   howto/nbresuse
+   howto/content/nbgitpuller
+   howto/content/add-data
+   howto/content/share-data
+
+The user environment
+--------------------
+
+.. toctree::
+   :titlesonly:
+
+   howto/env/user-environment
+   howto/env/notebook-interfaces
 
 Authentication
 --------------
@@ -73,6 +71,18 @@ with your JupyterHub. For more information on Authentication, see
 
    howto/auth/dummy
    howto/auth/github
+   howto/auth/firstuse
+
+Administration and security
+---------------------------
+
+.. toctree::
+   :titlesonly:
+
+   howto/admin/admin-users
+   howto/admin/resource-estimation
+   howto/admin/nbresuse
+   howto/admin/https
 
 Topic Guides
 ============

docs/install/add_packages.txt

@@ -26,4 +26,4 @@ The packages ``gdal`` and ``there`` are now available to all users in JupyterHub
 If a user already had a python notebook running, they have to restart their notebook's
 kernel to make the new libraries available.
 
-See :ref:`user_environment` for more information.
+See :ref:`howto/env/user_environment` for more information.

docs/install/custom-server.rst

@@ -33,16 +33,15 @@ Step 1: Installing The Littlest JupyterHub
 
 #. Copy the text below, and paste it into the terminal. 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
+   JupyterHub. Choose any name you like (don't forget to replace the brackets!).
+   This admin user can log in after the JupyterHub is set up, and
    can configure it to their needs. **Remember to add your username**!
 
    .. code-block:: bash
 
-      curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \
-        | sudo python3 - \
-          --admin <admin-user-name>
+      curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py | sudo python3 - --admin <admin-user-name>
 
-   .. note:
+   .. note::
 
       See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing.
       :ref:`topic/customizing-installer` documents other options that can be passed to the installer.
@@ -56,7 +55,8 @@ Step 1: Installing The Littlest JupyterHub
    .. image:: ../images/first-login.png
       :alt: JupyterHub log-in page
 
-#. Login using the **admin user name** you used in step 2, and a password. Use a
+#. Login using the **admin user name** you used in step 2. You can choose any
+   password that you wish. Use a
    strong password & note it down somewhere, since this will be the password for
    the admin user account from now on.
 

docs/install/digitalocean.rst

@@ -43,7 +43,7 @@ Let's create the server on which we can run JupyterHub.
    (4GB RAM, 2CPUs, 20 USD / month) is not a bad start. You can resize your server
    later if you need.
 
-   Check out our guide on How To :ref:`howto/resource-estimation` to help pick
+   Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
    how much Memory, CPU & disk space your server needs.
 
 #. Scroll down to **Select additional options**, and select **User data**.

docs/install/google.rst

@@ -83,7 +83,7 @@ Let's create the server on which we can run JupyterHub.
    .. image:: ../images/providers/google/machine-type-advanced.png
       :alt: Select a customized VM size
 
-   Check out our guide on How To :ref:`howto/resource-estimation` to help pick
+   Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
    how much Memory / CPU your server needs.
 
 #. Under **Boot Disk**, click the **Change** button. This lets us change the
@@ -109,7 +109,7 @@ Let's create the server on which we can run JupyterHub.
    to a hard drive. **SSD persistent disk** gives you a faster but more expensive
    disk, similar to an SSD.
 
-   Check out our guide on How To :ref:`howto/resource-estimation` to help pick
+   Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
    how much Disk space your server needs.
 
 #. Click the **Select** button to dismiss the Boot disk popup and go back to the

docs/install/jetstream.rst

@@ -54,7 +54,7 @@ Let's create the server on which we can run JupyterHub.
    #. Give your server a descriptive **Instance Name**.
    #. Select an appropriate **Instance Size**. We suggest m1.medium or larger.
 
-      Check out our guide on How To :ref:`howto/resource-estimation` to help pick
+      Check out our guide on How To :ref:`howto/admin/resource-estimation` to help pick
       how much Memory, CPU & disk space your server needs.
 
    #. If you have multiple allocations, make sure you are 'charging' this server

docs/topic/security.rst

@@ -70,4 +70,4 @@ HTTPS
 =====
 
 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`.
+information on how to use HTTPS with your JupyterHub, see :ref:`howto/admin/https`.