Merge pull request #3 from moshekruger/notebook-edits

Notebook edits

docs/index.rst

@@ -92,12 +92,12 @@ Documentation contents
 
 .. toctree::
    :maxdepth: 2
-   :caption: Notebooks
+   :caption: Jupyter Notebooks in Neptune
 
    Introduction <notebooks/introduction.rst>
    Installation for Jupyter and JupyterLab <notebooks/installation.rst>
    Configuration <notebooks/configuration.rst>
-   Integrations (AWS, SageMaker, Colab) <notebooks/integrations.rst>
+   Integrations with AWS and SageMaker <notebooks/integrations.rst>
    Troubleshoot <notebooks/troubleshoot.rst>
 
 .. toctree::

docs/notebooks/configuration.rst

@@ -1,46 +1,44 @@
-Configuration
-=============
-Simple configuration wizard lets you to setup your work with Neptune.
+Connecting the Jupyter Extension to Your Neptune Account
+========================================================
 
-**Step 1**
+After you have successfully `installed the Jupyter extension for Neptune <installation.html>`_, 
+you connect it to your Neptune account.
 
-Click **Configure** button (if you cannot see it, just hit **F5**).
+**Procedure**
 
-.. image:: ../_static/images/notebooks/buttons_01_1.png
-   :target: ../_static/images/notebooks/buttons_01_1.png
+1. In Jupyter, click **Connect to Neptune**.
+
+.. image:: ../_static/images/notebooks/connect_button.png
+   :target: ../_static/images/notebooks/connect_button.png
    :alt: image
 
-**Step 2**
 
-You see **Configure connection to Neptune**. Paste API Token first, then select project:
+The **Configure your connection to Neptune** dialog appears. 
 
-* *API Token* - take one from your account. :ref:`Check this <token-location>`, if you do not know where *API Token* is located. This field is validated automatically.
-* *Select project* - pick one from the drop down list.
-* Click **Create notebook**.
+.. image:: ../_static/images/notebooks/configure_connect.png
+   :target: ../_static/images/notebooks/configure_connect.png
+   :alt: image
 
-.. warning:: Your *API Token* is private and unique. Never share it. It's like sharing password.
 
-.. image:: ../_static/images/notebooks/checkpoint_01.png
-   :target: ../_static/images/notebooks/checkpoint_01.png
-   :alt: image
+2. Leave the dialog open and switch to the Neptune UI.
 
-.. image:: ../_static/images/notebooks/checkpoint_02.png
-   :target: ../_static/images/notebooks/checkpoint_02.png
-   :alt: image
+3. In the Neptune UI, obtain your API Token and copy it to the clipboard.
 
-.. image:: ../_static/images/notebooks/checkpoint_03.png
-   :target: ../_static/images/notebooks/checkpoint_03.png
-   :alt: image
+   a. In the upper right corner, click the avatar, and then click **Get API Token**.
+
+    .. image:: ../_static/images/notebooks/get_api_token.png
+        :target: ../_static/images/notebooks/get_api_token.png
+        :alt: image
 
-.. note:: Success! You just created new notebook with first checkpoint in the project you selected.
+   b. In the dialog that appears, click the **Copy to clipboard** button on the right. Then click **Close**.
 
-**Step 3**
+4. Switch back to Jupyter. In the dialog you left open, paste the token you copied to the clipboard. Click **Connect**.
 
-* You can use *this link* at the top, to go directly to this notebook in Neptune.
-* Click **Integrate** button to run environment variables export. It allows Neptune to checkpoint your work correctly. Moreover, you will be able to run Neptune experiments directly from notebook.
+   A confirmation message is displayed. It contains a link through which you can go directly to this Notebook in Neptune.
 
-.. image:: ../_static/images/notebooks/integration_01.png
-   :target: ../_static/images/notebooks/integration_01.png
-   :alt: image
+.. warning:: Your *API Token* is private and unique. Never share it. It's like sharing password.
+
+
+5. To conclude, to see experiments that you will run associated with this Notebook, click **Activate**. 
+In the dialog that appears, click **Activate**.
 
-.. note:: Re-run **Integrate** each time you reset or restart your kernel.

docs/notebooks/installation.rst

@@ -1,77 +1,177 @@
-Installation for Jupyter and JupyterLab
-=======================================
+Installing neptune-notebooks 
+============================
+This page provides instructions for installing neptune-notebooks -- the Neptune Jupyter extension. 
 
-Jupyter
--------
-Install `neptune-notebooks extension <https://github.com/neptune-ai/neptune-notebooks>`_:
+The extension enables the integration of Neptune and Jupyter or JupyterLab.
+
+When the extension is successfully installed, 
+you will be able to upload notebooks to Neptune, check out previously uploaded Notebooks, 
+and track experiments and metrics directly from the Jupyter UI. 
+Neptune versions the Notebook automatically once an experiment has started.
+
+About neptune-notebooks
+-----------------------
+
+neptune-notebooks is a Python package hosted `here <https://pypi.org/project/neptune-notebooks>`_. It includes:
+
+- A very basic CLI (command line interface) for uploading notebooks.
+- Standard Jupyter extension. The extension is written in Javascript and is visible in the web-based Jupyter UI. It is not hosted anywhere separately, only as part of the python package.
+- JupyterLab extension. The extension is written in Javascript and is visible in the web-based Jupyter UI. It is hosted `here <https://www.npmjs.com/package/neptune-notebooks>`_.
+
+
+Installation for Jupyter
+------------------------
+
+.. tip:: When installing Python packages, it is best practice to work in a `virtual environment <https://virtualenv.pypa.io/en/latest/>`_. 
+
+Procedure
+
+1. Install `neptune-notebooks extension <https://github.com/neptune-ai/neptune-notebooks>`_:
 
 .. code-block:: bash
 
    pip install neptune-notebooks
 
-Then enable extension for your Jupyter:
+2. Enable the extension for Jupyter:
 
 .. code-block:: bash
 
    jupyter nbextension enable --py neptune-notebooks
 
-Remember to install Neptune-client, if you did not do so already:
+3. Install Neptune client, if you did not do so already:
 
 .. code-block:: bash
 
    pip install neptune-client
 
-JupyterLab
-----------
 
-Requirements
-^^^^^^^^^^^^
-`Node.js <https://nodejs.org/en>`_ and `npm <https://www.npmjs.com/get-npm>`_ are required.
+Installation for JupyterLab
+---------------------------
 
-To check if you have Node.js installed, run this command in your terminal:
+JupyterLab is the next-generation web-based UI for Project Jupyter. 
 
-.. code-block:: bash
+When you install JupyterLab using ``pip install jupyterlab``, the standard Jupyter is also installed, as a dependency.
+
+
+**Installation methods**
+
+You can install the extension using any of the following three methods:
+
+- Through the command line (full neptune-notebooks package)
+- Through the command line (JupyterLab extension only)
+- Using the Extension Manager (JupyterLab extension only)
+
+Details for these methods follow below.
+
+**Requirements**
+
+Irrespective of which method you use, the following must be preinstalled on your system before you begin.
+
+- `Node.js <https://nodejs.org/en>`_ 
+- `npm <https://www.npmjs.com/get-npm>`_
+- `JupyterLab <https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html>`_
+
+.. tip:: When installing Python packages, it is best practice to work in a `virtual environment <https://virtualenv.pypa.io/en/latest/>`_. 
+
+
+Method 1: Install the full neptune-notebooks package through the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Pros**
+
+This is the most comprehensive type of installation:
 
-    node -v
+- It includes extensions for both standard Jupyter and JupyterLab. 
+- It also installs a CLI for uploading Notebook files.
+- The the neptune-client package is a dependency.
 
+**Cons**
 
-To confirm that you have npm installed you can run this command in your terminal:
+- After the installation, you still have to perform some manual actions in JupyterLab. 
+- This method may not be the easiest way of installing extensions in JupyterLab.
+
+**Procedure**
+
+1. In the console, run:
+
+.. code-block:: bash
+
+    pip install neptune-notebooks
+
+2. Start JupyterLab by running:
 
 .. code-block:: bash
 
-    npm -v
+    jupyter lab
+
+3. In the "Build Recommended" notification that is displayed, click **Build**.
+
+.. note:: The build process takes up to several minutes.
+
+4. In the "Build Complete" notification that is displayed, click **Reload**.
+
+The extension is loaded.
+
+Method 2: Install the JupyterLab extension only through the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method installs only the extension to JupyterLab.
 
-If you do not have them, please refer to: `installation instructions <https://www.npmjs.com/get-npm>`_.
+**Cons**
 
-Using command line
-^^^^^^^^^^^^^^^^^^
-Install `neptune-notebooks <https://www.npmjs.com/package/neptune-notebooks>`_ for your JupyterLab. In terminal run:
+The neptune-notebooks pip package, neptune-client pip package and extension to the standard Jupyter are not installed.
+
+**Pros**
+
+This method gives you more flexibility. For example, the extension can be running on a 
+different machine than your code that is executed from the Notebook.
+
+**Procedure**
+
+1. In the console, run:
 
 .. code-block:: bash
 
     jupyter labextension install neptune-notebooks
 
-Remember to install Neptune-client, if you did not do so already:
+2. Start JupyterLab by running:
 
 .. code-block:: bash
 
-   pip install neptune-client
+    jupyter lab
+
+3. In the "Build Recommended" notification that is displayed, click **Build**.
+4. In the "Build Complete" notification that is displayed, click **Reload**.
 
-Using JupyterLab extension manager (alternative)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-**Step 1**
+Method 3: Install the JupyterLab extension only, using the JupyterLab Extension Manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Enable extension manager. Select "Commands" (third icon on left panel), then click on "Enable Extension Manager (experimental)"
+**Procedure**
 
-.. image:: ../_static/images/notebooks/ext-manager-1.png
-   :target: ../_static/images/notebooks/ext-manager-1.png
-   :alt: enable extension manager
+1. In JupyterLab, enable Extension Manager, by clicking **Settings** > **Enable Extension Manager (experimental)**.
 
-**Step 2**
+.. image:: ../_static/images/notebooks/extension_manager.png
+   :target: ../_static/images/notebooks/extension_manager.png
+   :alt: Enable extension manager
 
-Go to "Extension Manager" (third icon on left panel) and search for "neptune-notebooks". Click "Install", then "Enable".
+2. Find neptune-notebooks and click **Install**.
 
 .. image:: ../_static/images/notebooks/ext-manager-2.png
    :target: ../_static/images/notebooks/ext-manager-2.png
    :alt: go to extension manager and search for neptune-notebooks
+
+
+Checking if the Installation was Successful
+-------------------------------------------
+
+Provided you have `configured <configuration.html>`_ Jupyter correctly, the following Neptune buttons appear in Jupyter notebooks:
+
+.. image:: ../_static/images/notebooks/buttons_11.png
+    :target: ../_static/images/notebooks/buttons_11.png
+    :alt: image
+
+- **Neptune**: For modifying configuration.
+- **Upload**: For creating a new checkpoint in Neptune.
+- **Download**: For downloading a specific checkpoint from Neptune.
+- **Activate**: Associates experiments you will be running with this Notebook.