Merge pull request #786 from minrk/4.1-docs

4.1 changelog and docs
10 years ago · c882b27732
parent feb83d6c9d 8024000a0e
commit c882b27732
16 changed files with 124 additions and 101 deletions
--- a/docs/source/_static/images/command-palette-41.png
+++ b/docs/source/_static/images/command-palette-41.png
--- a/docs/source/_static/images/find-replace-41.png
+++ b/docs/source/_static/images/find-replace-41.png
--- a/docs/source/_static/images/multi-select-41.png
+++ b/docs/source/_static/images/multi-select-41.png
--- a/docs/source/changelog.rst
+++ b/docs/source/changelog.rst
@ -6,14 +6,39 @@ Jupyter notebook changelog
 A summary of changes in the Jupyter notebook.
 For more detailed information, see `GitHub <https://github.com/jupyter/notebook>`__.

-4.1.x
+4.1.0
 -----

+Numerous bugfixes, including:
+
 - Properly handle reaping of zombie subprocesses.
+- Cross-origin fixes
+- Fix double-escaping of base URL prefix
+- More graceful handling of invalid unicode filenames
+- ANSI color-processing fixes
+
+
+UI Changes:
+
 - Moved the cell toolbar selector into the view menu `[screencast] <https://cloud.githubusercontent.com/assets/335567/10711889/59665a5a-7a3e-11e5-970f-86b89592880c.gif>`__.
- Added the ability to mark cells and perform actions on those cells
- Added the command palette
- Added the search and replace dialog
+- Add Restart & Run All to Kernel menu. Can be added as keyboard shortcut for action ``restart-kernel-and-run-all-cells``.
+- Added multiple-cell selection (``Shift-Up/Down`` to extend selection), and actions on multiple-cells, including cut/copy/paste and execute.
+
+  .. image:: /_static/images/multi-select-41.png
+  
+- Added a command palette for executing Jupyter actions by name
+
+  .. image:: /_static/images/command-palette-41.png
+  
+- Added the find and replace dialog (in the Edit menu or ``F`` in command-mode).
+
+  .. image:: /_static/images/find-replace-41.png
+
+Other improvements:
+
+- Custom KernelManager methods can be Tornado coroutines, allowing async operations.
+
+

 4.0.x
 -----
--- a/docs/source/examples/Notebook/JavaScript
+++ b/docs/source/examples/Notebook/JavaScript
@ -119,10 +119,9 @@
   },
   "outputs": [],
   "source": [
-    "import os.path\n",
-    "profile_dir = '~/.jupyter'\n",
-    "profile_dir = os.path.expanduser(profile_dir)\n",
-    "profile_dir"
+    "from jupyter_core.paths import jupyter_config_dir\n",
+    "jupyter_dir = jupyter_config_dir()\n",
+    "jupyter_dir"
   ]
  },
  {
@ -141,7 +140,7 @@
   "outputs": [],
   "source": [
    "import os.path\n",
-    "custom_js_path = os.path.join(profile_dir,'custom','custom.js')"
+    "custom_js_path = os.path.join(jupyter_dir, 'custom', 'custom.js')"
   ]
  },
  {
@ -155,8 +154,7 @@
    "#  my custom js\n",
    "if os.path.isfile(custom_js_path):\n",
    "    with open(custom_js_path) as f:\n",
-    "        for l in f: \n",
-    "            print(l)\n",
+    "        print(f.read())\n",
    "else:\n",
    "    print(\"You don't have a custom.js file\")  "
   ]
@ -206,7 +204,7 @@
   "cell_type": "markdown",
   "metadata": {},
   "source": [
-    "#### For the quick ones : "
+    "### For the quick ones : "
   ]
  },
  {
@ -491,7 +489,7 @@
   "cell_type": "markdown",
   "metadata": {},
   "source": [
-    "Try to wrap the all code in a file, put this file in `{profile}/static/custom/<a-name>.js`, and add \n",
+    "Try to wrap the all code in a file, put this file in `{jupyter_dir}/custom/<a-name>.js`, and add \n",
    "\n",
    "```\n",
    "require(['custom/<a-name>']);\n",
--- a/docs/source/examples/Notebook/Typesetting
+++ b/docs/source/examples/Notebook/Typesetting
@ -186,7 +186,8 @@
    "\n",
    "You will notice in other places on the web that `$$` are needed explicitly to begin and end MathJax typesetting.  This is **not** required if you will be using TeX environments, but the Jupyter notebook will accept this syntax on legacy notebooks.  \n",
    "\n",
-    "### Source\n",
+    "## Source\n",
+    "\n",
    "```\n",
    "$$\n",
    "\\begin{array}{c}\n",
@ -220,7 +221,8 @@
    "$$\n",
    "```\n",
    "\n",
-    "### Display\n",
+    "## Display\n",
+    "\n",
    "$$\n",
    "\\begin{array}{c}\n",
    "y_1 \\\\\\\n",
@ -264,7 +266,7 @@
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
-   "version": "3.4.0"
+   "version": "3.4.3"
  }
 },
 "nbformat": 4,
--- a/docs/source/examples/Notebook/rstversions/Connecting
+++ b/docs/source/examples/Notebook/rstversions/Connecting
@ -5,7 +5,7 @@ Connecting to an existing IPython kernel using the Qt Console
 =============================================================

 The Frontend/Kernel Model
-=========================
+-------------------------

 The traditional IPython (``ipython``) consists of a single process that
 combines a terminal based UI with the process that runs the users code.
@ -36,7 +36,7 @@ This Notebook describes how you would connect another Frontend to a
 Kernel that is associated with a Notebook.

 Manual connection
-=================
+-----------------

 To connect another Frontend to a Kernel manually, you first need to find
 out the connection information for the Kernel using the
@ -50,7 +50,7 @@ You can see that this magic displays everything you need to connect to
 this Notebook's Kernel.

 Automatic connection using a new Qt Console
-===========================================
+-------------------------------------------

 You can also start a new Qt Console connected to your current Kernel by
 using the ``%qtconsole`` magic. This will detect the necessary
--- a/docs/source/examples/Notebook/rstversions/Custom
+++ b/docs/source/examples/Notebook/rstversions/Custom
@ -66,6 +66,6 @@ back to it's initial behavior:

    %%javascript
    
-    Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', 'ipython.change-cell-to-raw');
+    Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', 'jupyter-notebook:change-cell-to-raw');

 `View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Custom%20Keyboard%20Shortcuts.ipynb>`__
--- a/docs/source/examples/Notebook/rstversions/Examples
+++ b/docs/source/examples/Notebook/rstversions/Examples
@ -11,7 +11,7 @@ can download the original interactive notebook files using the links at
 the tops and bottoms of the pages.

 Tutorials
-=========
+---------

 -  `What is the Jupyter
   Notebook <What%20is%20the%20Jupyter%20Notebook.html>`__
@ -24,7 +24,7 @@ Tutorials
   Extensions <JavaScript%20Notebook%20Extensions.html>`__

 Examples
-========
+--------

 -  `Importing Notebooks <Importing%20Notebooks.html>`__
 -  `Connecting with the Qt
--- a/docs/source/examples/Notebook/rstversions/Importing
+++ b/docs/source/examples/Notebook/rstversions/Importing
@ -54,7 +54,7 @@ Import hooks typically take the form of two objects:
                

 Notebook Loader
-===============
+---------------

 Here we have our Notebook Loader. It's actually quite simple - once we
 figure out the filename of the module, all it does is:
@ -114,7 +114,7 @@ this step is unnecessary.


 The Module Finder
-=================
+-----------------

 The finder is a simple object that tells you whether a name can be
 imported, and returns the appropriate loader. All this one does is
@ -152,7 +152,7 @@ Any extra logic is just for resolving paths within packages.


 Register the hook
-=================
+-----------------

 Now we register the ``NotebookFinder`` with ``sys.meta_path``

@ -171,7 +171,7 @@ Let's look at what we have in the CWD:
 So I should be able to ``import nbimp.mynotebook``.

 Aside: displaying notebooks
-===========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Here is some simple code to display the contents of a notebook with
 syntax highlighting, etc.
@ -236,7 +236,7 @@ Even the function that contains IPython syntax works:
    mynotebook.has_ip_syntax()

 Notebooks in packages
-=====================
+---------------------

 We also have a notebook inside the ``nb`` package, so let's make sure
 that works as well.
--- a/docs/source/examples/Notebook/rstversions/JavaScript
+++ b/docs/source/examples/Notebook/rstversions/JavaScript
@ -23,7 +23,7 @@ effort - development of small extensions that customize the behavior of
 the web interface.

 Tampering with the Notebook application
-=======================================
+---------------------------------------

 The first tool that is available to you and that you should be aware of
 are browser "developers tool". The exact naming can change across
@ -40,10 +40,10 @@ Those will be your best friends to debug and try different approaches
 for your extensions.

 Injecting JS
-============
+~~~~~~~~~~~~

 Using magics
-============
+^^^^^^^^^^^^

 The above tools can be tedious for editing edit long JavaScript files.
 Therefore we provide the ``%%javascript`` magic. This allows you to
@ -68,7 +68,7 @@ replaced by a JavaScript dropdown menu to select the save interval.
    %autosave??

 custom.js
-=========
+^^^^^^^^^

 To inject Javascript we provide an entry point: ``custom.js`` that
 allows the user to execute and load other resources into the notebook.
@ -80,29 +80,27 @@ in the behavior of the notebook.
 custom.js with others.

 Back to theory
-==============
+''''''''''''''

 .. code:: python

-    import os.path
-    profile_dir = '~/.jupyter'
-    profile_dir = os.path.expanduser(profile_dir)
-    profile_dir
+    from jupyter_core.paths import jupyter_config_dir
+    jupyter_dir = jupyter_config_dir()
+    jupyter_dir

 and custom js is in

 .. code:: python

    import os.path
-    custom_js_path = os.path.join(profile_dir,'custom','custom.js')
+    custom_js_path = os.path.join(jupyter_dir, 'custom', 'custom.js')

 .. code:: python

    #  my custom js
    if os.path.isfile(custom_js_path):
        with open(custom_js_path) as f:
-            for l in f: 
-                print(l)
+            print(f.read())
    else:
        print("You don't have a custom.js file")  

@ -116,7 +114,7 @@ aggressive), *creating* a file in ``static/`` directory needs a **server
 restart**.

 Exercise :
-==========
+----------

 -  Create a ``custom.js`` in the right location with the following
   content:
@ -133,7 +131,7 @@ custom.js <https://github.com/jupyter/notebook/blob/4.0.x/notebook/static/custom
 to see it's content and for more explanation.

 For the quick ones :
-====================
+~~~~~~~~~~~~~~~~~~~~

 We've seen above that you can change the autosave rate by using a magic.
 This is typically something I don't want to type every time, and that I
@ -182,7 +180,7 @@ Create a dropdown element in the toolbar (DOM
    }

 A non-interactive example first
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 I like my cython to be nicely highlighted

@ -197,7 +195,7 @@ does not screw up the highlighting. ``reg``\ is a list or regular
 expression that will trigger the change of mode.

 Get more documentation
-======================
+^^^^^^^^^^^^^^^^^^^^^^

 Sadly, you will have to read the js source file (but there are lots of
 comments) and/or build the JavaScript documentation using yuidoc. If you
@ -223,7 +221,7 @@ have ``node`` and ``yui-doc`` installed:
 and browse http://127.0.0.1:3000 to get documentation

 Some convenience methods
-========================
+^^^^^^^^^^^^^^^^^^^^^^^^

 By browsing the documentation you will see that we have some convenience
 methods that allows us to avoid re-inventing the UI every time :
@ -245,7 +243,7 @@ icons <http://fortawesome.github.io/Font-Awesome/icons/>`__ you can
 select from.

 Cell Metadata
-=============
+-------------

 The most requested feature is generally to be able to distinguish an
 individual cell in the notebook, or run a specific action with them. To
@ -254,7 +252,7 @@ rely on ``CellToolbar``. This allows you to register a set of actions
 and graphical elements that will be attached to individual cells.

 Cell Toolbar
-============
+~~~~~~~~~~~~

 You can see some example of what can be done by toggling the
 ``Cell Toolbar`` selector in the toolbar on top of the notebook. It
@ -268,7 +266,7 @@ this element wis registered with. Then we will need to register that
 function and give it a name.

 Register a callback
-===================
+^^^^^^^^^^^^^^^^^^^

 .. code:: python

@ -296,7 +294,7 @@ Register a callback
     CellToolbar.register_callback('tuto.foo', toggle);

 Registering a preset
-====================
+^^^^^^^^^^^^^^^^^^^^

 This function can now be part of many ``preset`` of the CellToolBar.

@ -317,7 +315,7 @@ click the button, and that when saved on reloaded the metadata is still
 available.

 Exercise:
-=========
+^^^^^^^^^

 Try to wrap the all code in a file, put this file in
 ``{profile}/static/custom/<a-name>.js``, and add
@ -368,7 +366,7 @@ plugin <https://github.com/ipython-contrib/IPython-notebook-extensions/blob/mast
    })

 For the quickest
-================
+^^^^^^^^^^^^^^^^

 Try to use `the
 following <https://github.com/ipython/ipython/blob/1.x/IPython/html/static/notebook/js/celltoolbar.js#L367>`__
--- a/docs/source/examples/Notebook/rstversions/Notebook
+++ b/docs/source/examples/Notebook/rstversions/Notebook
@ -5,14 +5,14 @@ Notebook Basics
 ===============

 Running the Notebook Server
-===========================
+---------------------------

 The Jupyter notebook server is a custom web server that runs the
 notebook web application. Most of the time, users run the notebook
 server on their local computer using the command line interface.

 Starting the notebook server using the command line
-===================================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 You can start the notebook server from the command line (Terminal on
 Mac/Linux, CMD prompt on Windows) by running the following command:
@ -34,7 +34,7 @@ server in the highest directory in your filesystem where notebooks can
 be found. Often this will be your home directory.

 Additional options
-==================
+~~~~~~~~~~~~~~~~~~

 By default, the notebook server starts on port 8888. If port 8888 is
 unavailable, the notebook server searchs the next available port.
@ -59,7 +59,7 @@ can be displayed with the ``--help`` flag:
    jupyter notebook --help

 The Notebook dashboard
-======================
+----------------------

 When you first start the notebook server, your browser will open to the
 notebook dashboard. The dashboard serves as a home page for the
@ -97,7 +97,7 @@ This view provides a convenient way to track notebooks that you start as
 you navigate the file system in a long running notebook server.

 Overview of the Notebook UI
-===========================
+---------------------------

 If you create a new notebook or open an existing one, you will be taken
 to the notebook user interface (UI). This UI allows you to run code and
@ -112,7 +112,7 @@ The notebook has an interactive tour of these elements that can be
 started in the "Help:User Interface Tour" menu item.

 Modal editor
-============
+------------

 Starting with IPython 2.0, the Jupyter Notebook has a modal user
 interface. This means that the keyboard does different things depending
@ -120,7 +120,7 @@ on which mode the Notebook is in. There are two modes: edit mode and
 command mode.

 Edit mode
-=========
+~~~~~~~~~

 Edit mode is indicated by a green cell border and a prompt showing in
 the editor area:
@ -140,7 +140,7 @@ cell's editor area.
   </div>

 Command mode
-============
+~~~~~~~~~~~~

 Command mode is indicated by a grey cell border:

@ -174,7 +174,7 @@ Enter command mode by pressing ``Esc`` or using the mouse to click
   </div>

 Mouse navigation
-================
+----------------

 All navigation and actions in the Notebook are available using the mouse
 through the menubar and toolbar, which are both above the main Notebook
@ -237,7 +237,7 @@ button in the toolbar or the "Cell:Run" menu item. To unrender the
 selected cell, double click on the cell.

 Keyboard Navigation
-===================
+-------------------

 The modal user interface of the Jupyter Notebook has been optimized for
 efficient keyboard usage. This is made possible by having two different
--- a/docs/source/examples/Notebook/rstversions/Running
+++ b/docs/source/examples/Notebook/rstversions/Running
@ -11,7 +11,7 @@ single kernel. This notebook is associated with the IPython kernel,
 therefor runs Python code.

 Code cells allow you to enter and run code
-==========================================
+------------------------------------------

 Run a code cell using ``Shift-Enter`` or pressing the

@ -39,7 +39,7 @@ There are two other keyboard shortcuts for running code:
 -  ``Ctrl-Enter`` run the current cell and enters command mode.

 Managing the Kernel
-===================
+-------------------

 Code is run in a separate process called the Kernel. The Kernel can be
 interrupted or restarted. Try running the following cell and then hit
@ -75,7 +75,7 @@ segfault the Python interpreter:
    libc.time(-1)  # BOOM!!

 Cell menu
-=========
+---------

 The "Cell" menu has a number of menu items for running code in different
 ways. These includes:
@ -87,7 +87,7 @@ ways. These includes:
 -  Run All Below

 Restarting the kernels
-======================
+----------------------

 The kernel maintains the state of a notebook's computations. You can
 reset this state by restarting the kernel. This is done by clicking on
@ -104,7 +104,7 @@ the
 in the toolbar above.

 sys.stdout and sys.stderr
-=========================
+-------------------------

 The stdout and stderr streams are displayed as text in the output area.

@ -118,7 +118,7 @@ The stdout and stderr streams are displayed as text in the output area.
    print('hi, stderr', file=sys.stderr)

 Output is asynchronous
-======================
+----------------------

 All output is displayed asynchronously as it is generated in the Kernel.
 If you execute the next cell, you will see the output one piece at a
@ -132,7 +132,7 @@ time, not all at the end.
        time.sleep(0.5)

 Large outputs
-=============
+-------------

 To better handle large outputs, the output area can be collapsed. Run
 the following cell and then single- or double- click on the active area
--- a/docs/source/examples/Notebook/rstversions/Typesetting
+++ b/docs/source/examples/Notebook/rstversions/Typesetting
@ -38,10 +38,10 @@ Display
   \end{align}

 The Cauchy-Schwarz Inequality
-=============================
+-----------------------------

 Source
------
+~~~~~~

 ::

@ -50,7 +50,7 @@ Source
    \end{equation*}

 Display
-------
+~~~~~~~

 .. raw:: latex

@ -59,10 +59,10 @@ Display
   \end{equation*}

 A Cross Product Formula
-=======================
+-----------------------

 Source
------
+~~~~~~

 ::

@ -75,7 +75,7 @@ Source
    \end{equation*}

 Display
-------
+~~~~~~~

 .. raw:: latex

@ -88,10 +88,10 @@ Display
   \end{equation*}

 The probability of getting (k) heads when flipping (n) coins is
-===============================================================
+---------------------------------------------------------------

 Source
------
+~~~~~~

 ::

@ -100,7 +100,7 @@ Source
    \end{equation*}

 Display
-------
+~~~~~~~

 .. raw:: latex

@ -109,10 +109,10 @@ Display
   \end{equation*}

 An Identity of Ramanujan
-========================
+------------------------

 Source
------
+~~~~~~

 ::

@ -123,7 +123,7 @@ Source
    \end{equation*}

 Display
-------
+~~~~~~~

 .. raw:: latex

@ -134,10 +134,10 @@ Display
   \end{equation*}

 A Rogers-Ramanujan Identity
-===========================
+---------------------------

 Source
------
+~~~~~~

 ::

@ -148,7 +148,7 @@ Source
    \end{equation*}

 Display
-------
+~~~~~~~

 .. raw:: latex

@ -159,10 +159,10 @@ Display
   \end{equation*}

 Maxwell's Equations
-===================
+-------------------

 Source
------
+~~~~~~

 ::

@ -173,7 +173,7 @@ Source
    \end{align}

 Display
-------
+~~~~~~~

 .. raw:: latex

@ -190,20 +190,20 @@ Equation numbering and referencing will be available in a future version
 of the Jupyter notebook.

 Inline Typesetting (Mixing Markdown and TeX)
-============================================
+--------------------------------------------

 While display equations look good for a page of samples, the ability to
 mix math and *formatted* **text** in a paragraph is also important.

 Source
------
+~~~~~~

 ::

    This expression $\sqrt{3x-1}+(1+x)^2$ is an example of a TeX inline equation in a [Markdown-formatted](http://daringfireball.net/projects/markdown/) sentence.  

 Display
-------
+~~~~~~~

 This expression :math:`\sqrt{3x-1}+(1+x)^2` is an example of a TeX
 inline equation in a
--- a/docs/source/examples/Notebook/rstversions/What
+++ b/docs/source/examples/Notebook/rstversions/What
@ -5,7 +5,7 @@ What is the Jupyter Notebook?
 =============================

 Introduction
-============
+------------

 The Jupyter Notebook is an **interactive computing environment** that
 enables users to author notebook documents that include: - Live code -
@ -19,7 +19,7 @@ systems (like git/\ `GitHub <http://github.com>`__) or
 `nbviewer.jupyter.org <http://nbviewer.jupyter.org>`__.

 Components
-==========
+~~~~~~~~~~

 The Jupyter Notebook combines three components:

@ -38,7 +38,7 @@ The Jupyter Notebook combines three components:
   objects. Each notebook document has its own kernel.

 Notebook web application
-========================
+------------------------

 The notebook web application enables users to:

@ -61,7 +61,7 @@ The notebook web application enables users to:
   `MathJax <http://www.mathjax.org/>`__.

 Kernels
-=======
+-------

 Through Jupyter's kernel and messaging architecture, the Notebook allows
 code to be run in a range of different programming languages. For each
@ -90,7 +90,7 @@ Most users don't need to know about these details, but it helps to
 understand that "kernels run code."

 Notebook documents
-==================
+------------------

 Notebook documents contain the **inputs and outputs** of an interactive
 session as well as **narrative text** that accompanies the code but is
--- a/docs/source/examples/Notebook/rstversions/Working
+++ b/docs/source/examples/Notebook/rstversions/Working
@ -11,7 +11,7 @@ can be found here:
 http://daringfireball.net/projects/markdown/

 Markdown basics
-===============
+---------------

 You can make text *italic* or **bold**.

@ -64,7 +64,7 @@ And shorthand for links:
 `Jupyter's website <http://jupyter.org>`__

 Headings
-========
+--------

 You can add headings by starting a line with one (or multiple) ``#``
 followed by a space, as in the following example:
@ -82,7 +82,7 @@ Heading 2.2
 -----------

 Embedded code
-=============
+-------------

 You can embed code meant for illustration instead of execution in
 Python:
@ -103,7 +103,7 @@ or other languages:
    }

 LaTeX equations
-===============
+---------------

 Courtesy of MathJax, you can include mathematical expressions both
 inline: :math:`e^{i\pi} + 1 = 0` and displayed:
@ -124,7 +124,7 @@ Expressions on their own line are surrounded by ``$$``:
    $$e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i$$

 Github flavored markdown (GFM)
-==============================
+------------------------------

 The Notebook webapp support Github flavored markdown meaning that you
 can use triple backticks for code blocks
@ -170,7 +170,7 @@ A nice Html Table
 +--------+---------+

 General HTML
-============
+------------

 Because Markdown is a superset of HTML you can even add things like HTML
 tables:
@ -268,7 +268,7 @@ row 2, cell 2
   </table>

 Local files
-===========
+-----------

 If you have local files in your Notebook directory, you can refer to
 these files in Markdown cells directly:
@ -297,7 +297,7 @@ These do not embed the data into the notebook file, and require that the
 files exist when you are viewing the notebook.

 Security of local files
-=======================
+~~~~~~~~~~~~~~~~~~~~~~~

 Note that this means that the Jupyter notebook server also acts as a
 generic file server for files inside the same tree as your notebooks.