Update README.rst

CHANGES.rst

@@ -6,7 +6,7 @@ Changelog for Jupyter-O2
 
 **Removed:**
 
-* This version removes compatibility with Python 2.7,
+- This version removes compatibility with Python 2.7,
   which has not been supported since version 1.0.2.
 
 **Improvements:**

README.rst

@@ -26,21 +26,21 @@ Next, on your local machine:
 
 Install Jupyter-O2.
 
-.. code-block:: console
+.. code-block:: bash
 
     pip install jupyter-o2
 
 Then, generate the config file.
 
-.. code-block:: console
+.. code-block:: bash
 
     jupyter-o2 --generate-config
 
 Follow the printed path to ``jupyter-o2.cfg`` and edit according to its instructions, particularly the
 ``DEFAULT_USER`` and ``INIT_JUPYTER_COMMANDS`` fields.
 You may copy this file to any of the locations listed by ``jupyter-o2 --paths`` if you wish.
 
-Make sure you have X11 forwarding active (e.g. install `XQuartz <https://www.xquartz.org/>`_ if on a Mac).
+Make sure you have X11 forwarding active (install `XQuartz <https://www.xquartz.org/>`_ if on a Mac).
 
 For more info on setting up Jupyter and troubleshooting Jupyter-O2, see the `jupyter-o2 tips`_.
 
@@ -50,7 +50,7 @@ Usage
 ------------------------------
 Jupyter-O2 should be run locally using the following command format:
 
-.. code-block:: console
+.. code-block:: bash
 
     jupyter-o2 [subcommand]
 
@@ -62,7 +62,7 @@ on the `O2 wiki <https://wiki.rc.hms.harvard.edu/display/O2/Jupyter+on+O2>`_.
 
 Note that if Jupyter is installed on your machine, Jupyter-O2 can also be run as a Jupyter subcommand:
 
-.. code-block:: console
+.. code-block:: bash
 
     jupyter o2 lab
 

jupyter_o2_tips.rst

@@ -2,6 +2,54 @@
 Jupyter-O2 tips
 ===============
 
+--------------------------------------------------------------------------------------------------------------------
+Troubleshooting
+--------------------------------------------------------------------------------------------------------------------
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+X11 error / missing DISPLAY variable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you see ``srun: error: x11: no local DISPLAY defined``,
+``No DISPLAY variable set``, or similar, you probably need to
+install or reinstall `XQuartz <https://www.xquartz.org/>`__.
+
+To test outside of Jupyter-O2, log in to the server with ``ssh -X``
+and check your DISPLAY using ``echo $DISPLAY``.
+There should be a string printed in response.
+
+A possible alternative is to run Jupyter-O2 with the
+``-Y`` argument to enable trusted X11 forwarding (less secure).
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+SSH error: pxssh error: could not synchronize with original prompt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are not on the HMS network or using the HMS VPN,
+you will need to tell Jupyter-O2 use two-factor authentication
+with the arguments ``--2fa --2fa-code 1``.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+nbsignatures.db
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If Jupyter hangs when opening notebooks for the first time in any
+session, and the console shows error messages such as:
+
+.. code-block::
+
+    > The signatures database cannot be opened; maybe it is corrupted or encrypted.
+    > Failed commiting signatures database to disk.
+
+Disabling Jupyter's signatures database may be the best option, since there is
+no non-networked file system shared between all the interactive compute
+nodes.
+
+1. Enter an interactive session and generate a notebook config using
+   ``jupyter notebook --generate-config``
+2. In ``~/.jupyter/jupyter_notebook_config.py`` set
+   ``c.NotebookNotary.db_file = ':memory:'``
+
 --------------------------------------------------------------------------------------------------------------------
 Useful Jupyter add-ons
 --------------------------------------------------------------------------------------------------------------------
@@ -56,51 +104,3 @@ JupyterLab is now
 JupyterLab offers a more complete environment than Jupyter Notebook.
 With tabs for notebooks, terminals, consoles, text editors, and an integrated file browser,
 you could run almost anything you need on O2 from a single browser window.
-
---------------------------------------------------------------------------------------------------------------------
-Troubleshooting
---------------------------------------------------------------------------------------------------------------------
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-X11 error / missing DISPLAY variable
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you see ``srun: error: x11: no local DISPLAY defined``,
-``No DISPLAY variable set``, or similar, you probably need to
-install or reinstall `XQuartz <https://www.xquartz.org/>`__.
-
-To test outside of Jupyter-O2, log in to the server with ``ssh -X``
-and check your DISPLAY using ``echo $DISPLAY``.
-There should be a string printed in response.
-
-A possible alternative is to run Jupyter-O2 with the
-``-Y`` argument to enable trusted X11 forwarding (less secure).
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-SSH error: pxssh error: could not synchronize with original prompt
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you are not on the HMS network or using the HMS VPN,
-you will need to tell Jupyter-O2 use two-factor authentication
-with the arguments ``--2fa --2fa-code 1``.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-nbsignatures.db
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If Jupyter hangs when opening notebooks for the first time in any
-session, and the console shows error messages such as:
-
-.. code-block::
-
-    > The signatures database cannot be opened; maybe it is corrupted or encrypted.
-    > Failed commiting signatures database to disk.
-
-Disabling Jupyter's signatures database may be the best option, since there is
-no non-networked file system shared between all the interactive compute
-nodes.
-
-1. Enter an interactive session and generate a notebook config using
-   ``jupyter notebook --generate-config``
-2. In ``~/.jupyter/jupyter_notebook_config.py`` set
-   ``c.NotebookNotary.db_file = ':memory:'``