@Carreau 's review comments.

examples/Notebook/Converting Notebooks With nbconvert.ipynb

@@ -1,317 +1,317 b''
 {
  "cells": [
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "# NbConvert"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Command line usage"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "`NbConvert` is both a library and command line tool that allows you to convert notebooks to other formats.  It ships with many common formats: `html`, `latex`, `markdown`, `python`, `rst`, and  `slides`\n",
     "NbConvert relys on the Jinja templating engine, so implementing a new format or tweeking an existing one is easy."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "You can invoke nbconvert by running\n",
     "\n",
     "```bash\n",
     "$ ipython nbconvert <options and arguments>\n",
     "```\n",
     "\n",
     "Call `ipython nbconvert` with the `--help` flag or without any aruments to display the basic help.  For detailed configuration help, use the `--help-all` flag."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Basic export"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "As a test, the `Index.ipynb` notebook in the directory will be convert. \n",
     "\n",
-    "If you're converting a notebook with code in it, make sure to run the code cells that you're interested in before attempting to convert the notebook.  Nbconvert **does not execute the code cell** of the notebooks that it converts."
+    "If you're converting a notebook with code in it, make sure to run the code cells that you're interested in before attempting to convert the notebook.  Unless explicitly requested, nbconvert **does not execute the code cells** of the notebooks that it converts."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%%bash\n",
     "ipython nbconvert  'Index.ipynb'"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Html is the (configurable) default value.  The verbose form of the same command as above is "
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%%bash\n",
     "ipython nbconvert  --to=html 'Index.ipynb'"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "You can also convert to latex, which will extract the embeded images.  If the embeded images are SVGs, inkscape is used to convert them to pdf:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%%bash\n",
     "ipython nbconvert  --to=latex 'Index.ipynb'"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Note that the latex conversion creates latex, not a PDF.  To create a PDF you need the required third party packages to compile the latex.\n",
     "\n",
     "A `--post` flag is provided for convinience which allows you to have nbconvert automatically compile a PDF for you from your output."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%%bash\n",
     "ipython nbconvert  --to=latex 'Index.ipynb' --post=pdf"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Custom templates"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Look at the first 20 lines of the `python` exporter"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "pyfile = !ipython nbconvert --to python 'Index.ipynb' --stdout\n",
     "for l in pyfile[20:40]:\n",
     "    print l"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "From the code, you can see that non-code cells are also exported.  If you want to change this behavior, you can use a custom template.  The custom template inherits from the Python template and overwrites the markdown blocks so that they are empty."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%%writefile simplepython.tpl\n",
     "{% extends 'python.tpl'%}\n",
     "\n",
     "{% block markdowncell -%}\n",
     "{% endblock markdowncell %}\n",
     "\n",
     "## we also want to get rig of header cell\n",
     "{% block headingcell -%}\n",
     "{% endblock headingcell %}\n",
     "\n",
     "## and let's change the appearance of input prompt\n",
     "{% block in_prompt %}\n",
     "# This was input cell with prompt number : {{ cell.prompt_number if cell.prompt_number else ' ' }}\n",
     "{%- endblock in_prompt %}"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "pyfile = !ipython nbconvert --to python 'Index.ipynb' --stdout --template=simplepython.tpl\n",
     "\n",
     "for l in pyfile[4:40]:\n",
     "    print l\n",
     "print '...'"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For details about the template syntax, refer to [Jinja's manual](http://jinja.pocoo.org/docs/dev/)."
+    "For details about the template syntax, refer to [Jinja's manual](http://jinja2.readthedocs.org/en/latest/intro.html)."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Template that use cells metadata"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The notebook file format supports attaching arbitrary JSON metadata to each cell.  Here, as an exercise, you will use the metadata to tags cells."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "First you need to choose another notebook you want to convert to html, and tag some of the cell with metadata.  You can refere to the file `soln/celldiff.js` as an example or follow the Javascript tutorial to figure out how do change cell metadata.  Assuming you have a notebook with some of the cells tagged as `Easy`|`Medium`|`Hard`|`<None>`, the notebook can be converted specially using a custom template.  Design your remplate in the cells provided below.\n",
+    "First you need to choose another notebook you want to convert to html, and tag some of the cells with metadata.  You can refere to the file `soln/celldiff.js` as an example or follow the Javascript tutorial to figure out how do change cell metadata.  Assuming you have a notebook with some of the cells tagged as `Easy`|`Medium`|`Hard`|`<None>`, the notebook can be converted specially using a custom template.  Design your remplate in the cells provided below.\n",
     "\n",
     "The following, unorganized lines of code, may be of help:"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "```\n",
     "{% extends 'html_full.tpl'%}\n",
     "{% block any_cell %}\n",
     "{{ super() }}\n",
     "<div style=\"background-color:red\">\n",
     "<div style='background-color:orange'>\n",
     "```\n",
     "\n",
     "If your key name under `cell.metadata.example.difficulty`, the following code would get the value of it:\n",
     "\n",
     "`cell['metadata'].get('example',{}).get('difficulty','')`\n",
     "\n",
     "Tip: Use `%%writefile` to edit the template in the notebook."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%%bash\n",
     "# ipython nbconvert --to html <your chosen notebook.ipynb> --template=<your template file>"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "%loadpy soln/coloreddiff.tpl"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
     "collapsed": false
    },
    "outputs": [],
    "source": [
     "# ipython nbconvert --to html '04 - Custom Display Logic.ipynb' --template=soln/coloreddiff.tpl"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Get rid of all command line flags."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "IPython nbconvert can be configured using the default profile and by selecting a non-default a profile via `--profile` flag.  Additionally, if a `config.py` file exist in current working directory, nbconvert will use that as config."
+    "IPython nbconvert can be configured using the default profile or a profile specified via the `--profile` flag.  Additionally, if a `config.py` file exist in current working directory, nbconvert will use that as config."
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
     "version": 3
    },
    "file_extension": ".py",
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.4.3"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 0
 }

examples/Notebook/Notebook Basics.ipynb

@@ -1,313 +1,313 b''
 {
  "cells": [
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "# Notebook Basics"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Running the Notebook Server"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The IPython 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 IPython's command line interface."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Starting the notebook server using the command line"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "You can start the notebook server from the command line (Terminal on Mac/Linux, CMD prompt on Windows) by running the following command: \n",
     "\n",
     "    ipython notebook\n",
     "\n",
     "This will print some information about the notebook server in your terminal, including the URL of the web application (by default, `http://127.0.0.1:8888`). It will then open your default web browser to this URL.\n",
     "\n",
-    "When the notebook opens, you will see the **notebook dashboard**, which will show a list of the notebooks and subdirectories in the directory where the notebook server was started (as seen in the next section, below). Most of the time, you will want to start a notebook server in the highest directory in your filesystem where notebooks can be found. Often this will be your home directory."
+    "When the notebook opens, you will see the **notebook dashboard**, which will show a list of the notebooks, files, and subdirectories in the directory where the notebook server was started (as seen in the next section, below). Most of the time, you will want to start a notebook server in the highest directory in your filesystem where notebooks can be found. Often this will be your home directory."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Additional options"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "You can start more than one notebook server at the same time. By default, the first notebook server starts on port 8888 and later notebook servers search for open ports near that one.\n",
     "\n",
     "You can also specify the port manually:\n",
     "\n",
     "    ipython notebook --port 9999\n",
     "\n",
     "Or start notebook server without opening a web browser.\n",
     "\n",
     "    ipython notebook --no-browser\n",
     "\n",
     "The notebook server has a number of other command line arguments that can be displayed with the `--help` flag: \n",
     "\n",
     "    ipython notebook --help"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## The Notebook dashboard"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "When you first start the notebook server, your browser will open to the notebook dashboard. The dashboard serves as a home page for the notebook. Its main purpose is to display the notebooks and files in the current directory. For example, here is a screenshot of the dashboard page for the `examples` directory in the IPython repository:\n",
     "\n",
     "<img src=\"images/dashboard_files_tab.png\" width=\"791px\"/>"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The top of the notebook list displays clickable breadcrumbs of the current directory. By clicking on these breadcrumbs or on sub-directories in the notebook list, you can navigate your file system.\n",
     "\n",
     "To create a new notebook, click on the \"New\" button at the top of the list and select a kernel from the dropdown (as seen below).  Which kernels are listed depend on what's installed on the server.  Some of the kernels in the screenshot below may not exist as an option to you.\n",
     "\n",
     "<img src=\"images/dashboard_files_tab_new.png\" width=\"202px\" />"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Notebooks and files can be uploaded to the current directory by dragging a notebook file onto the notebook list or by the \"click here\" text above the list.\n",
     "\n",
     "The notebook list shows green \"Running\" text and a green notebook icon next to running notebooks (as seen below). Notebooks remain running until you explicitly shut them down; closing the notebook's page is not sufficient.\n",
     "\n",
     "<img src=\"images/dashboard_files_tab_run.png\" width=\"777px\"/>"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "To shutdown, delete, duplicate, or rename a notebook check the checkbox next to it and an array of controls will appear at the top of the notebook list (as seen below).  You can also use the same operations on directories and files when applicable.\n",
     "\n",
     "<img src=\"images/dashboard_files_tab_btns.png\" width=\"301px\" />"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "To see all of your running notebooks along with their directories, click on the \"Running\" tab:\n",
     "\n",
     "<img src=\"images/dashboard_running_tab.png\" width=\"786px\" />\n",
     "\n",
     "This view provides a convenient way to track notebooks that you start as you navigate the file system in a long running notebook server."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Overview of the Notebook UI"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "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 author notebook documents interactively. The notebook UI has the following main areas:\n",
     "\n",
     "* Menu\n",
     "* Toolbar\n",
     "* Notebook area and cells\n",
     "\n",
     "The notebook has an interactive tour of these elements that can be started in the \"Help:User Interface Tour\" menu item."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Modal editor"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Starting with IPython 2.0, the IPython Notebook has a modal user interface. This means that the keyboard does different things depending on which mode the Notebook is in. There are two modes: edit mode and command mode."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Edit mode"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Edit mode is indicated by a green cell border and a prompt showing in the editor area:\n",
     "\n",
     "<img src=\"images/edit_mode.png\">\n",
     "\n",
     "When a cell is in edit mode, you can type into the cell, like a normal text editor."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "<div class=\"alert alert-success\">\n",
     "Enter edit mode by pressing `Enter` or using the mouse to click on a cell's editor area.\n",
     "</div>"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "### Command mode"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "Command mode is indicated by a grey cell border:\n",
     "\n",
     "<img src=\"images/command_mode.png\">\n",
     "\n",
     "When you are in command mode, you are able to edit the notebook as a whole, but not type into individual cells. Most importantly, in command mode, the keyboard is mapped to a set of shortcuts that let you perform notebook and cell actions efficiently. For example, if you are in command mode and you press `c`, you will copy the current cell - no modifier is needed."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "<div class=\"alert alert-error\">\n",
     "Don't try to type into a cell in command mode; unexpected things will happen!\n",
     "</div>"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "<div class=\"alert alert-success\">\n",
     "Enter command mode by pressing `Esc` or using the mouse to click *outside* a cell's editor area.\n",
     "</div>"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Mouse navigation"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "All navigation and actions in the Notebook are available using the mouse through the menubar and toolbar, which are both above the main Notebook area:\n",
     "\n",
     "<img src=\"images/menubar_toolbar.png\" width=\"786px\" />"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The first idea of mouse based navigation is that **cells can be selected by clicking on them.** The currently selected cell gets a grey or green border depending on whether the notebook is in edit or command mode. If you click inside a cell's editor area, you will enter edit mode. If you click on the prompt or output area of a cell you will enter command mode.\n",
     "\n",
     "If you are running this notebook in a live session (not on http://nbviewer.ipython.org) try selecting different cells and going between edit and command mode. Try typing into a cell."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The second idea of mouse based navigation is that **cell actions usually apply to the currently selected cell**. Thus if you want to run the code in a cell, you would select it and click the <button class='btn btn-default btn-xs'><i class=\"fa fa-play icon-play\"></i></button> button in the toolbar or the \"Cell:Run\" menu item. Similarly, to copy a cell you would select it and click the <button class='btn btn-default btn-xs'><i class=\"fa fa-copy icon-copy\"></i></button> button in the toolbar or the \"Edit:Copy\" menu item. With this simple pattern, you should be able to do most everything you need with the mouse.\n",
     "\n",
     "Markdown and heading cells have one other state that can be modified with the mouse. These cells can either be rendered or unrendered. When they are rendered, you will see a nice formatted representation of the cell's contents. When they are unrendered, you will see the raw text source of the cell. To render the selected cell with the mouse, click the <button class='btn btn-default btn-xs'><i class=\"fa fa-play icon-play\"></i></button> button in the toolbar or the \"Cell:Run\" menu item. To unrender the selected cell, double click on the cell."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Keyboard Navigation"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "The modal user interface of the IPython Notebook has been optimized for efficient keyboard usage. This is made possible by having two different sets of keyboard shortcuts: one set that is active in edit mode and another in command mode.\n",
     "\n",
     "The most important keyboard shortcuts are `Enter`, which enters edit mode, and `Esc`, which enters command mode.\n",
     "\n",
     "In edit mode, most of the keyboard is dedicated to typing into the cell's editor. Thus, in edit mode there are relatively few shortcuts.  In command mode, the entire keyboard is available for shortcuts, so there are many more.  The `Help`->`Keyboard Shortcuts` dialog lists the available shortcuts."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "We recommend learning the command mode shortcuts in the following rough order:\n",
     "\n",
     "1. Basic navigation: `enter`, `shift-enter`, `up/k`, `down/j`\n",
     "2. Saving the notebook: `s`\n",
     "2. Cell types: `y`, `m`, `1-6`, `t`\n",
     "3. Cell creation: `a`, `b`\n",
     "4. Cell editing: `x`, `c`, `v`, `d`, `z`, `shift+=`\n",
     "5. Kernel operations: `i`, `.`"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
     "version": 3
    },
    "file_extension": ".py",
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.4.3"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 0
 }