Merge pull request #24 from choldgraf/docs

Small text improvements + adding copy buttons to text blocks

docs/_static/custom.css

@@ -0,0 +1,22 @@
+button.copybtn {
+  webkit-transition: opacity .3s ease-in-out;
+  -o-transition: opacity .3s ease-in-out;
+  transition: opacity .3s ease-in-out;
+  opacity: 0;
+  padding: 2px 6px;
+  position: absolute;
+  right: 4px;
+  top: 4px;
+}
+
+div.highlight:hover .copybtn, div.highlight .copybtn:focus {
+    opacity: .3;
+}
+
+div.highlight .copybtn:hover {
+    opacity: 1;
+}
+
+div.highlight {
+    position: relative;
+}

docs/_static/custom.js

@@ -0,0 +1,25 @@
+// Set up copy/paste for code blocks
+function addCopyButtonToCode(){
+  // get all <code> elements
+  var allCodeBlocksElements = $( "div.highlight pre" );
+
+  allCodeBlocksElements.each(function(ii) {
+   	// add different id for each code block
+
+  	// target
+    var currentId = "codeblock" + (ii + 1);
+    $(this).attr('id', currentId);
+
+    //trigger
+    var clipButton = '<button class="btn copybtn" data-clipboard-target="#' + currentId + '"><img src="https://clipboardjs.com/assets/images/clippy.svg" width="13" alt="Copy to clipboard"></button>';
+       $(this).after(clipButton);
+    });
+
+    new Clipboard('.btn');
+}
+
+$(document).ready(function () {
+  // Highlight current page in sidebar
+  console.log('hi');
+  addCopyButtonToCode();
+});

docs/conf.py

@@ -10,6 +10,12 @@ version = ''
 # The full version, including alpha/beta/rc tags
 release = 'v0.1'
 
+# Add custom CSS/Javascript
+def setup(app):
+    app.add_javascript("custom.js")
+    app.add_stylesheet("custom.css")
+    app.add_javascript("https://cdn.jsdelivr.net/npm/clipboard@1/dist/clipboard.min.js")
+
 # Enable MathJax for Math
 extensions = ['sphinx.ext.mathjax']
 

docs/guides/admin.rst

@@ -7,9 +7,9 @@ In The Littlest JupyterHub, we try to allow users to do as many administrative
 tasks as possible within JupyterHub itself. Admin users can:
 
 1. Have full root access with passwordless ``sudo``
-2. Install systemwide packages with ``apt``
+2. Install system-wide packages with ``apt``
-3. Install ``conda`` / ``pip`` packages for all JupyterHub
+3. Install ``conda`` / ``pip`` packages for all JupyterHub users
-4. Change amount of RAM / CPU available to each user and more!
+4. Change the amount of RAM / CPU available to each user, and more!
 
 By default, there are no admin users. You should add some after installation.
 
@@ -17,7 +17,8 @@ Adding admin users
 ==================
 
 Admin users are specified in the `YAML <https://en.wikipedia.org/wiki/YAML>`_
-config file at ``/opt/tljh/config.yaml``.
+config file at ``/opt/tljh/config.yaml``. This file is created upon installing
+tljh.
 
 1. Open the ``config.yaml`` file for editing.
 

docs/guides/install.rst

@@ -15,7 +15,7 @@ The quick way to install The Littlest JupyterHub (tljh) is:
 This takes 2-5 minutes to run. When completed, you can access your new JupyterHub
 at the public IP of your server!
 
-You should probably add yourself as an `admin user <admin.md>`_
+You should probably add yourself as an `admin user <admin.rst>`_
 after installation.
 
 Slightly less quick installation

docs/guides/notebook-interfaces.rst

@@ -10,7 +10,7 @@ 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
+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
@@ -20,13 +20,12 @@ 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.
+* **For the JupyterLab interface**: change ``/tree`` to ``/lab``.
-
+* **For the nteract interface**: change ``/tree`` to ``/nteract``
-If you change ``/tree`` to ``/nteract``, you will get the nteract interface.
 
 You can play around with them and see what fits your use cases best.
 
-Changing default notebook interface
+Changing the default user interface
 -----------------------------------
 
 You can change the default interface users get when they log in by modifying

docs/index.rst

@@ -28,6 +28,7 @@ started!
 .. toctree::
    :titlesonly:
 
+   tutorials/quickstart
    tutorials/digitalocean
    tutorials/jetstream
    tutorials/google

docs/troubleshooting/logs.rst

@@ -7,7 +7,7 @@ Looking at Logs
 They contain a forensic record of what individual pieces of software were doing
 before things went bad, and can help us understand the problem so we can fix it.
 
-TLJH collects logs from JupyterHub, Configurable HTTP Proxy & from each individual
+TLJH collects logs from JupyterHub, Configurable HTTP Proxy, & from each individual
 user's notebook server. All the logs are accessible via `journalctl <https://www.freedesktop.org/software/systemd/man/journalctl.html>`_.
 
 .. warning::
@@ -58,8 +58,9 @@ problems after that.
 
    sudo journalctl -u jupyter-<name-of-user>
 
-This command displays logs from the given user's notebook server. See :ref:`journalctl_tips`
+This command displays logs from the given user's notebook server. You can get a
-for tips on navigating the logs.
+list of all users from the "users" button at the top-right of the Admin page.
+See :ref:`journalctl_tips` for tips on navigating the logs.
 
 .. _journalctl_tips:
 

docs/tutorials/add_packages.txt

@@ -0,0 +1,29 @@
+The **User Environment** is a conda environment that is shared by all users
+in the JupyterHub. Libraries installed in this environment are immediately
+available to all users. Admin users can install packages in this environment
+with ``sudo -E``.
+
+#. Log in as an admin user and open a Terminal in your Jupyter Notebook.
+
+   .. image:: ../images/notebook/new-terminal-button.png
+      :alt: New Terminal button under New menu
+
+#. Install `gdal <https://anaconda.org/conda-forge/gdal>`_ from `conda-forge <https://conda-forge.org/>`_.
+
+   .. code-block:: bash
+
+      sudo -E conda install -c conda-forge gdal
+
+   The ``sudo -E`` is very important!
+
+#. Install ``there`` with ``pip``
+
+   .. code-block:: bash
+
+      sudo -E pip install there
+
+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.

docs/tutorials/add_users.txt

@@ -0,0 +1,39 @@
+Most administration & configuration of the JupyterHub can be done from the
+web UI directly. Let's add a few users who can log in!
+
+#. 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.
+
+   .. image:: ../images/admin/add-users-dialog.png
+      :alt: Adding users with add users dialog
+
+   You can tick the **Admin** checkbox if you want to give admin rights to all
+   these users too.
+
+#. Click the **Add Users** button in the dialog box. Your users are now added
+   to the JupyterHub! When they log in for the first time, they can set their
+   password - and use it to log in again in the future.
+
+Congratulations, you now have a multi user JupyterHub that you can add arbitrary
+users to!

docs/tutorials/digitalocean.rst

@@ -100,78 +100,12 @@ Let's create the server on which we can run JupyterHub.
 
 #. Congratulations, you have a running working JupyterHub!
 
-Step 2: Addding more users
+Step 2: Adding more users
 --------------------------
 
-Most administration & configuration of the JupyterHub can be done from the
+.. include:: add_users.txt
-web UI directly. Let's add a few users who can log in!
-
-#. 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.
-
-   .. image:: ../images/admin/add-users-dialog.png
-      :alt: Adding users with add users dialog
-
-   You can tick the **Admin** checkbox if you want to give admin rights to all
-   these users too.
-
-#. Click the **Add Users** button in the dialog box. Your users are now added
-   to the JupyterHub! When they log in for the first time, they can set their
-   password - and use it to log in again in the future.
-
-Congratulations, you now have a multi user JupyterHub that you can add arbitrary
-users to!
 
 Step 3: Install conda / pip packages for all users
 --------------------------------------------------
 
-The **User Environment** is a conda environment that is shared by all users
+.. include:: add_packages.txt
-in the JupyterHub. Libraries installed in this environment are immediately
-available to all users. Admin users can install packages in this environment
-with ``sudo -E``.
-
-#. Log in as an admin user and open a Terminal in your Jupyter Notebook.
-
-   .. image:: ../images/notebook/new-terminal-button.png
-      :alt: New Terminal button under New menu
-
-#. Install `gdal <https://anaconda.org/conda-forge/gdal>`_ from `conda-forge <https://conda-forge.org/>`_.
-
-   .. code-block:: bash
-
-      sudo -E conda install -c conda-forge gdal
-
-   The ``sudo -E`` is very important!
-
-#. Install ``there`` with ``pip``
-
-   .. code-block:: bash
-
-      sudo -E pip install there
-
-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.

docs/tutorials/google.rst

@@ -82,6 +82,9 @@ 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
 
+   For more guidance on the different options available to you, as well as
+   pricing considerations on Google Cloud, see the `GCP Choosing a VM Guide <https://cloud.google.com/compute/docs/instances/creating-instance-with-custom-machine-type?hl=en_US>`_.
+   
 #. Under **Boot Disk**, click the **Change** button. This lets us change the
    operating system and the size of your disk.
 
@@ -183,82 +186,11 @@ Let's create the server on which we can run JupyterHub.
 #. Congratulations, you have a running working JupyterHub!
 
 Step 2: Adding more users
--------------------------
+--------------------------
 
-Most administration & configuration of the JupyterHub can be done from the
+.. include:: add_users.txt
-web UI directly. Let's add a few users who can log in!
-
-#. 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.
-
-   .. image:: ../images/admin/add-users-dialog.png
-      :alt: Adding users with add users dialog
-
-   You can tick the **Admin** checkbox if you want to give admin rights to all
-   these users too.
-
-#. Click the **Add Users** button in the dialog box. Your users are now added
-   to the JupyterHub! When they log in for the first time, they can set their
-   password - and use it to log in again in the future.
-
-   **Note**: These users will be added as UNIX users on the underlying
-   Jetstream instance, too, and admin users will have ``sudo`` privileges.
-   (The user will be created the first time the user's server is started,
-   e.g. upon first login.)
-
-Congratulations, you now have a multi user JupyterHub that you can add arbitrary
-users to!
 
 Step 3: Install conda / pip packages for all users
 --------------------------------------------------
 
-The **User Environment** is a conda environment that is shared by all users
+.. include:: add_packages.txt
-in the JupyterHub. Libraries installed in this environment are immediately
-available to all users. Admin users can install packages in this environment
-with ``sudo -E``.
-
-#. Log in as an admin user and open a Terminal in your Jupyter Notebook.
-
-   .. image:: ../images/notebook/new-terminal-button.png
-      :alt: New Terminal button under New menu
-
-#. For example, try installing `gdal <https://anaconda.org/conda-forge/gdal>`_ from `conda-forge <https://conda-forge.org/>`_.
-
-   .. code-block:: bash
-
-      sudo -E conda install -y -c conda-forge gdal
-
-   The ``sudo -E`` is very important!
-
-#. Alternatively, try installing `there <https://pypi.org/project/there/>`_ with ``pip``.
-
-   .. code-block:: bash
-
-      sudo -E pip install there
-
-The packages ``gdal`` and ``there`` are now available to all users in JupyterHub.
-If a user already had a python notebook running, they need to restart their notebook's
-kernel to make the new libraries available.
-
-See :ref:`user_environment` for more information.

docs/tutorials/jetstream.rst

@@ -125,82 +125,11 @@ Let's create the server on which we can run JupyterHub.
 #. Congratulations, you have a running working JupyterHub!
 
 Step 2: Adding more users
--------------------------
+--------------------------
 
-Most administration & configuration of the JupyterHub can be done from the
+.. include:: add_users.txt
-web UI directly. Let's add a few users who can log in!
-
-#. 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.
-
-   .. image:: ../images/admin/add-users-dialog.png
-      :alt: Adding users with add users dialog
-
-   You can tick the **Admin** checkbox if you want to give admin rights to all
-   these users too.
-
-#. Click the **Add Users** button in the dialog box. Your users are now added
-   to the JupyterHub! When they log in for the first time, they can set their
-   password - and use it to log in again in the future.
-
-   **Note**: These users will be added as UNIX users on the underlying
-   Jetstream instance, too, and admin users will have ``sudo`` privileges.
-   (The user will be created the first time the user's server is started,
-   e.g. upon first login.)
-
-Congratulations, you now have a multi user JupyterHub that you can add arbitrary
-users to!
 
 Step 3: Install conda / pip packages for all users
 --------------------------------------------------
 
-The **User Environment** is a conda environment that is shared by all users
+.. include:: add_packages.txt
-in the JupyterHub. Libraries installed in this environment are immediately
-available to all users. Admin users can install packages in this environment
-with ``sudo -E``.
-
-#. Log in as an admin user and open a Terminal in your Jupyter Notebook.
-
-   .. image:: ../images/notebook/new-terminal-button.png
-      :alt: New Terminal button under New menu
-
-#. For example, try installing `gdal <https://anaconda.org/conda-forge/gdal>`_ from `conda-forge <https://conda-forge.org/>`_.
-
-   .. code-block:: bash
-
-      sudo -E conda install -y -c conda-forge gdal
-
-   The ``sudo -E`` is very important!
-
-#. Alternatively, try installing `there <https://pypi.org/project/there/>`_ with ``pip``.
-
-   .. code-block:: bash
-
-      sudo -E pip install there
-
-The packages ``gdal`` and ``there`` are now available to all users in JupyterHub.
-If a user already had a python notebook running, they need to restart their notebook's
-kernel to make the new libraries available.
-
-See :ref:`user_environment` for more information.