Merge pull request #3584 from takluyver/doc-troubleshooting

Documentation updates and organisation

docs/source/changelog.rst

@@ -1,7 +1,7 @@
 .. _changelog:
 
-Jupyter notebook changelog
-==========================
+Changelog
+=========
 
 A summary of changes in the Jupyter notebook.
 For more detailed information, see

docs/source/examples/Notebook/examples_index.rst

@@ -1,14 +1,13 @@
-`View the original notebooks on nbviewer`__
+=================
+Notebook Examples
+=================
+
+The pages in this section are all converted notebook files. You can also
+`view these notebooks on nbviewer`__.
 
 __ http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/
    docs/source/examples/Notebook/
 
-========
-Examples
-========
-
-The following notebooks have been rendered for your convenience.
-
 .. toctree::
    :maxdepth: 2
 

docs/source/index.rst

@@ -1,20 +1,23 @@
 ====================
-The Jupyter notebook
+The Jupyter Notebook
 ====================
 
+* `Installation <https://jupyter.readthedocs.io/en/latest/install.html>`_
+* `Starting the Notebook <https://jupyter.readthedocs.io/en/latest/running.html>`_
+
 .. toctree::
    :maxdepth: 1
    :caption: User Documentation
 
    notebook
-   Installation <https://jupyter.readthedocs.io/en/latest/install.html>
-   Running the Notebook <https://jupyter.readthedocs.io/en/latest/running.html>
-   Migrating from IPython <https://jupyter.readthedocs.io/en/latest/migrating.html>
    ui_components
+   examples/Notebook/examples_index.rst
+   troubleshooting
+   changelog
    comms
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Configuration
 
    config_overview
@@ -33,38 +36,8 @@ The Jupyter notebook
    development_release
    development_faq
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Community documentation
-
-   examples/Notebook/examples_index.rst
-   examples/Notebook/What is the Jupyter Notebook
-   examples/Notebook/Notebook Basics
-   examples/Notebook/Running Code
-   examples/Notebook/Working With Markdown Cells
-   examples/Notebook/Custom Keyboard Shortcuts
-   examples/Notebook/JavaScript Notebook Extensions
-   examples/Notebook/Importing Notebooks
-   examples/Notebook/Connecting with the Qt Console
-   examples/Notebook/Typesetting Equations
-
 .. toctree::
     :hidden:
 
     examples/Notebook/nbpackage/mynotebook.ipynb
     examples/Notebook/nbpackage/nbs/other.ipynb
-
-.. toctree::
-   :maxdepth: 2
-   :caption: About Jupyter Notebook
-
-   changelog
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Questions? Suggestions?
-
-   Jupyter mailing list <https://groups.google.com/forum/#!forum/jupyter>
-   Jupyter website <https://jupyter.org>
-   Stack Overflow - Jupyter <https://stackoverflow.com/questions/tagged/jupyter>
-   Stack Overflow - Jupyter-notebook <https://stackoverflow.com/questions/tagged/jupyter-notebook>

docs/source/notebook.rst

@@ -177,40 +177,32 @@ Notebook user interface
 -----------------------
 
 When you create a new notebook document, you will be presented with the
-**notebook name**, a **menu bar**, a **toolbar** and an empty **code
-cell**.
+**notebook name**, a **menu bar**, a **toolbar** and an empty **code cell**.
 
-**notebook name**: The name of the notebook document is displayed at the top
-of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
-of the ``.ipynb`` notebook document file.  Clicking on the notebook name
-brings up a dialog which allows you to rename it. Thus, renaming a notebook
+.. image:: ./_static/images/blank-notebook-ui.png
+
+**Notebook name**: The name displayed at the top of the page,
+next to the Jupyter logo, reflects the name of the ``.ipynb`` file.
+Clicking on the notebook name brings up a dialog which allows you to rename it.
+Thus, renaming a notebook
 from "Untitled0" to "My first notebook" in the browser, renames the
 ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
 
-**menu bar**: The menu bar presents different options that may be used to
+**Menu bar**: The menu bar presents different options that may be used to
 manipulate the way the notebook functions.
 
-**toolbar**: The tool bar gives a quick way of performing the most-used
+**Toolbar**: The tool bar gives a quick way of performing the most-used
 operations within the notebook, by clicking on an icon.
 
-**code cell**: the default type of cell, read on for an explanation of cells
-
-.. note::
-
-    As of notebook version 4.1, the user interface allows for multiple cells to
-    be selected.  The ``quick celltype selector``, found in the menubar, will
-    display a dash ``-`` when multiple cells are selected to indicate that the
-    type of the cells in the selection might not be unique. The quick selector
-    can still be used to change the type of the selection and will change the
-    type of all the currently selected cells.
+**Code cell**: the default type of cell; read on for an explanation of cells.
 
 
 Structure of a notebook document
 --------------------------------
 
 The notebook consists of a sequence of cells.  A cell is a multiline text input
 field, and its contents can be executed by using :kbd:`Shift-Enter`, or by
-clicking either the "Play" button the toolbar, or `Cell | Run` in the menu bar.
+clicking either the "Play" button the toolbar, or :guilabel:`Cell`, :guilabel:`Run` in the menu bar.
 The execution behavior of a cell is determined by the cell's type.  There are three
 types of cells: **code cells**, **markdown cells**, and **raw cells**.  Every
 cell starts off being a **code cell**, but its type can be changed by using a
@@ -224,9 +216,8 @@ see the `collection of examples
 Code cells
 ~~~~~~~~~~
 A *code cell* allows you to edit and write new code, with full syntax
-highlighting and tab completion. By default, the language associated to a code
-cell is Python, but other languages, such as ``Julia`` and ``R``, can be
-handled using :ref:`cell magic commands <magics_explained>`.
+highlighting and tab completion. The programming language you use depends
+on the *kernel*, and the default kernel (IPython) runs Python code.
 
 When a code cell is executed, code that it contains is sent to the kernel
 associated with the notebook.  The results that are returned from this
@@ -269,7 +260,7 @@ supports a `large subset <mathjax_tex>`_ of LaTeX functionality
 .. _mathjax_tex: https://docs.mathjax.org/en/latest/tex.html
 
 Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
-`amsmath` package) also work, such as
+``amsmath`` package) also work, such as
 ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
 New LaTeX macros may be defined using standard methods,
 such as ``\newcommand``, by placing them anywhere *between math delimiters* in
@@ -286,7 +277,7 @@ Raw cells
 *Raw* cells provide a place in which you can write *output* directly.
 Raw cells are not evaluated by the notebook.
 When passed through nbconvert_, raw cells arrive in the
-destination format unmodified. For example, this allows you to type full LaTeX
+destination format unmodified. For example, you can type full LaTeX
 into a raw cell, which will only be rendered by LaTeX after conversion by
 nbconvert.
 
@@ -306,17 +297,14 @@ correctly. This is much more convenient for interactive exploration than
 breaking up a computation into scripts that must be executed together, as was
 previously necessary, especially if parts of them take a long time to run.
 
-At certain moments, it may be necessary to interrupt a calculation which is
-taking too long to complete. This may be done with the `Kernel | Interrupt`
-menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
-Similarly, it may be necessary or desirable to restart the whole computational
-process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
+To interrupt a calculation which is taking too long, use the :guilabel:`Kernel`,
+:guilabel:`Interrupt` menu option, or the :kbd:`i,i` keyboard shortcut.
+Similarly, to restart the whole computational process,
+use the :guilabel:`Kernel`, :guilabel:`Restart` menu option or :kbd:`0,0`
 shortcut.
 
-A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
-menu option `File | Download as`. Choosing the ``.py`` option downloads a
-Python ``.py`` script, in which all rich output has been removed and the
-content of markdown cells have been inserted as comments.
+A notebook may be downloaded as a ``.ipynb`` file or converted to a number of
+other formats using the menu option :guilabel:`File`, :guilabel:`Download as`.
 
 .. seealso::
 
@@ -333,31 +321,16 @@ shortcuts are also available for the most common ones. The essential shortcuts
 to remember are the following:
 
 * :kbd:`Shift-Enter`:  run cell
-    Execute the current cell, show output (if any), and jump to the next cell
-    below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
-    cell will also be created. Note that in the notebook, typing :kbd:`Enter`
-    on its own *never* forces execution, but rather just inserts a new line in
-    the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
-    ``Cell | Run`` menu item.
-
-* :kbd:`Ctrl-Enter`: run cell in-place
-    Execute the current cell as if it were in "terminal mode", where any
-    output is shown, but the cursor *remains* in the current cell. The cell's
-    entire contents are selected after execution, so you can just start typing
-    and only the new input will be in the cell. This is convenient for doing
-    quick experiments in place, or for querying things like filesystem
-    content, without needing to create additional cells that you may not want
-    to be saved in the notebook.
-
-* :kbd:`Alt-Enter`: run cell, insert below
-    Executes the current cell, shows the output, and inserts a *new*
-    cell between the current cell and the cell below (if one exists). This
-    is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
-    (:kbd:`Ctrl-m a` adds a new cell above the current one.)
-
-* :kbd:`Esc` and :kbd:`Enter`: Command mode and edit mode
-    In command mode, you can easily navigate around the notebook using keyboard
-    shortcuts. In edit mode, you can edit text in cells.
+    Execute the current cell, show any output, and jump to the next cell below.
+    If :kbd:`Shift-Enter` is invoked on the last cell, it makes a new cell below.
+    This is equivalent to clicking the :guilabel:`Cell`, :guilabel:`Run` menu
+    item, or the Play button in the toolbar.
+
+* :kbd:`Esc`: Command mode
+    In command mode, you can navigate around the notebook using keyboard shortcuts.
+
+* :kbd:`Enter`: Edit mode
+    In edit mode, you can edit text in cells.
 
 For the full list of available shortcuts, click :guilabel:`Help`,
 :guilabel:`Keyboard Shortcuts` in the notebook menus.
@@ -375,64 +348,49 @@ Installing kernels
 For information on how to install a Python kernel, refer to the
 `IPython install page <https://ipython.org/install.html>`__.
 
-Kernels for other languages can be found in the `IPython wiki
-<https://github.com/ipython/ipython/wiki/IPython%20kernels%20for%20other%20languages>`_.
-They usually come with instruction what to run to make the kernel available
+The Jupyter wiki has a long list of `Kernels for other languages
+<https://github.com/jupyter/jupyter/wiki/Jupyter-kernels>`_.
+They usually come with instructions on how to make the kernel available
 in the notebook.
 
 
 .. _signing_notebooks:
 
-Signing Notebooks
------------------
+Trusting Notebooks
+------------------
 
 To prevent untrusted code from executing on users' behalf when notebooks open,
-we have added a signature to the notebook, stored in metadata.
+we store a signature of each trusted notebook.
 The notebook server verifies this signature when a notebook is opened.
-If the signature stored in the notebook metadata does not match,
-javascript and HTML output will not be displayed on load,
-and must be regenerated by re-executing the cells.
+If no matching signature is found,
+Javascript and HTML output will not be displayed
+until they are regenerated by re-executing the cells.
 
-Any notebook that you have executed yourself *in its entirety* will be
-considered trusted, and its HTML and javascript output will be displayed on
+Any notebook that you have fully executed yourself will be
+considered trusted, and its HTML and Javascript output will be displayed on
 load.
 
 If you need to see HTML or Javascript output without re-executing,
-you can explicitly trust notebooks, such as those shared with you,
-or those that you have written yourself prior to IPython 2.0,
+and you are sure the notebook is not malicious, you can tell Jupyter to trust it
 at the command-line with::
 
-    $ jupyter trust mynotebook.ipynb [other notebooks.ipynb]
-
-This just generates a new signature stored in each notebook.
+    $ jupyter trust mynotebook.ipynb
 
-You can generate a new notebook signing key with::
-
-    $ jupyter trust --reset
-
-.. include:: links.txt
+See :ref:`notebook_security` for more details about the trust mechanism.
 
 Browser Compatibility
 ---------------------
 
-The Jupyter Notebook is officially supported by the latest stable versions of the
-following browsers:
+The Jupyter Notebook aims to support the latest versions of these browsers:
 
 * Chrome
 * Safari
 * Firefox
 
-The is mainly due to the notebook's usage of WebSockets and the flexible box
-model.
-
-The following browsers are unsupported:
-
-* Safari < 5
-* Firefox < 6
-* Chrome < 13
-* Opera (any): CSS issues, but execution might work
-* Internet Explorer < 10
-* Internet Explorer ≥ 10 (same as Opera)
+Up to date versions of Opera and Edge may also work, but if they don't, please
+use one of the supported browsers.
 
 Using Safari with HTTPS and an untrusted certificate is known to not work
 (websockets will fail).
+
+.. include:: links.txt