"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 of IPython 2.0, the dashboard allows you to navigate to different subdirectories. Because of this, it is no longer necessary to start a separate notebook server for each subdirectory. 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.\n",
"\n",
"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\n",
"\n",
"<div class=\"alert alert-failure\">\n",
"It used to be possible to specify kernel options, such as <code>--pylab inline</code> from the command line. This is deprecated in IPython 2.0 and will be removed in IPython 3.0. To enable matplotlib based plotting for the Python kernel use the <code>%matplotlib</code> magic command.\n",
"`NbConvert` is the library, and the command line tool that allow to convert from notebook to other formats.\n",
"It is a technological preview in 1.0 but is already usable and highly configurable.\n",
"It ships already with many default available formats : `html`, `latex`, `markdown`, `python`, `rst` and `slides`\n",
"which are fully base on Jinja templating engine, so writing a converter for your custom format or tweeking the existing \n",
"one should be extra simple."
"`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 doing\n",
"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 no aruments to get basic help on how to use it.\n",
"For more information about configuration use the `--help-all` flag"
"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."
]
},
{
@ -50,230 +46,105 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"We will be converting `Custom Display Logic.ipynb`. \n",
"Be sure to have runed some of the cells in it to have output otherwise you will only see input in nbconvert.\n",
"Nbconvert **do not execute the code** in the notebook files, it only converts what is inside."
"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."
]
},
{
"cell_type": "code",
"execution_count": 1,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"[NbConvertApp] Using existing profile dir: u'/Users/bussonniermatthias/.ipython/profile_default'\n",
"[NbConvertApp] Converting notebook 04 - Custom Display Logic.ipynb to html\n",
"[NbConvertApp] Support files will be in 04 - Custom Display Logic_files/\n",
"[NbConvertApp] Loaded template html_full.tpl\n",
"[NbConvertApp] Writing 221081 bytes to 04 - Custom Display Logic.html\n"
"You can also convert to latex, which will take care of extractin the embeded base64 encoded png, or the svg and call inkscape to convert those svg to pdf if necessary :"
"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": 3,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"[NbConvertApp] Using existing profile dir: u'/Users/bussonniermatthias/.ipython/profile_default'\n",
"[NbConvertApp] Converting notebook 04 - Custom Display Logic.ipynb to latex\n",
"[NbConvertApp] Support files will be in 04 - Custom Display Logic_files/\n",
"Setting Language: .UTF-8\n",
"\n",
"(process:26432): Gtk-WARNING **: Locale not supported by C library.\n",
"\tUsing the fallback 'C' locale.\n",
"Setting Language: .UTF-8\n",
"\n",
"(process:26472): Gtk-WARNING **: Locale not supported by C library.\n",
"\tUsing the fallback 'C' locale.\n",
"Setting Language: .UTF-8\n",
"\n",
"(process:26512): Gtk-WARNING **: Locale not supported by C library.\n",
"\tUsing the fallback 'C' locale.\n",
"Setting Language: .UTF-8\n",
"\n",
"(process:26552): Gtk-WARNING **: Locale not supported by C library.\n",
"\tUsing the fallback 'C' locale.\n",
"Setting Language: .UTF-8\n",
"\n",
"(process:26592): Gtk-WARNING **: Locale not supported by C library.\n",
"Have a look at `04 - Custom Display Logic.pdf`, toward the end, where we compared `display()` vs `display_html()` and returning the object.\n",
"See how the cell where we use `display_html` was not able to display the circle, whereas the two other ones were able to select one of the oher representation they know how to display."
"## Custom templates"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Customizing template"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"let's look at the first 20 lines of the `python` exporter"
"Look at the first 20 lines of the `python` exporter"
]
},
{
"cell_type": "code",
"execution_count": 5,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"# 1. Implementing special display methods such as `_repr_html_`.\n",
"# 2. Registering a display function for a particular type.\n",
"# \n",
"# In this Notebook we show how both approaches work.\n",
"\n",
"# Before we get started, we will import the various display functions for displaying the different formats we will create.\n",
"# The main idea of the first approach is that you have to implement special display methods, one for each representation you want to use. Here is a list of the names of the special methods and the values they must return:\n",
"We see that the non-code cell are exported to the file. To have a cleaner script, we will export only the code contained in the code cells.\n",
"\n",
"To do so, we will inherit the python template, and overwrite the markdown blocks to be empty."
"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": 6,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Overwriting simplepython.tpl\n"
]
}
],
"outputs": [],
"source": [
"%%writefile simplepython.tpl\n",
"{% extends 'python.tpl'%}\n",
@ -321,57 +182,13 @@
},
{
"cell_type": "code",
"execution_count": 7,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"# This was input cell with prompt number : 54\n",
"I'll let you read Jinja manual for the exact syntax of the template."
"For details about the template syntax, refer to [Jinja's manual](http://jinja.pocoo.org/docs/dev/)."
]
},
{
@ -396,22 +213,22 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Notebook fileformat support attaching arbitrary JSON metadata to each cell of a notebook. In this part we will use those metadata."
"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.\n",
"You can see the file `soln/celldiff.js` for a solution on how to tag, or follow the javascript tutorial to see how to do that. Use what we have written there to tag cells of some notebooks to `Easy`|`Medium`|`Hard`|`<None>`, and convert this notebook using your template."
"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",
"\n",
"The following, unorganized lines of code, may be of help:"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"you might need the following : \n",
"```\n",
"{% extends 'html_full.tpl'%}\n",
"{% block any_cell %}\n",
@ -420,16 +237,16 @@
"<div style='background-color:orange'>\n",
"```\n",
"\n",
"`metadata` might not exist, be sure to :\n",
"If your key name under `cell.metadata.example.difficulty`, the following code would get the value of it:\n",
"tip: use `%%writefile` to edit the template in the notebook :-)"
"Tip: Use `%%writefile` to edit the template in the notebook."
]
},
{
"cell_type": "code",
"execution_count": 8,
"execution_count": null,
"metadata": {
"collapsed": false
},
@ -472,10 +289,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"As of all of IPython nbconvert can be configured using profiles and passing the `--profile` flag. \n",
"Moreover if a `config.py` file exist in current working directory nbconvert will use that, or read the config file you give to it with the `--config=<file>` flag. \n",
"\n",
"In the end, if you are often running nbconvert on the sam project, `$ ipython nbconvert` should be enough to get you up and ready."
"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."
"This notebook assumes that you already have IPython [installed](http://ipython.org/install.html) and are able to start the notebook server by running:\n",
"## 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",
"For more details on how to run the notebook server, see [Running the Notebook Server](Running the Notebook Server.ipynb)."
"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."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## The Notebook dashboard"
"### Additional options"
]
},
{
"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 in the current directory. For example, here is a screenshot of the dashboard page for the `examples` directory in the IPython repository:\n",
"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",
"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",
" ipython notebook --port 9999\n",
"\n",
"To create a new notebook, click on the \"New Notebook\" button at the top of the list.\n",
"Or start notebook server without opening a web browser.\n",
"\n",
"Notebooks 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",
" ipython notebook --no-browser\n",
"\n",
"The notebook list shows a red \"Shutdown\" button for running notebooks and a \"Delete\" button for stopped notebooks. Notebook remain running until you explicitly click the \"Shutdown\" button; closing the notebook's page is not sufficient.\n",
"The notebook server has a number of other command line arguments that can be displayed with the `--help` flag: \n",
"\n",
"To see all of your running notebooks along with their directories, click on the \"Running\" tab:\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",
"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",
"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",
"This view provides a convenient way to track notebooks that you start as you navigate the file system in a long running notebook server."
"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",
"As of IPython 2.0, the user interface has changed significantly. Because of this we highly recommend existing users to review this information after upgrading to IPython 2.0. All new users of IPython should review this information as well.\n",
"</div>"
"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",
"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"
]
},
{
@ -74,7 +142,7 @@
"* Toolbar\n",
"* Notebook area and cells\n",
"\n",
"IPython 2.0 has an interactive tour of these elements that can be started in the \"Help:User Interface Tour\" menu item."
"The notebook has an interactive tour of these elements that can be started in the \"Help:User Interface Tour\" menu item."
]
},
{
@ -167,7 +235,7 @@
"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",
"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:\n",
"\n",
"<img src=\"images/edit_shortcuts.png\">"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In command mode, the entire keyboard is available for shortcuts, so there are many more:\n",
"\n",
"<img src=\"images/command_shortcuts.png\">"
"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."
"The default kernel runs Python code. When it is released in the Summer/Fall of 2014, IPython 3.0 will provide a simple way for users to pick which of these kernels is used for a given notebook. \n",
"The default kernel runs Python code. IPython 3.0 provides a simple way for users to pick which of these kernels is used for a given notebook. \n",
"\n",
"Each of these kernels communicate with the notebook web application and web browser using a JSON over ZeroMQ/WebSockets message protocol that is described [here](http://ipython.org/ipython-doc/dev/development/messaging.html). Most users don't need to know about these details, but it helps to understand that \"kernels run code.\""
]
@ -137,7 +137,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"When you run the notebook web application on your computer, notebook documents are just **files on your local filesystem with a `.ipynb` extension**. This allows you to use familiar workflows for organizing your notebooks into folders and sharing them with others using email, Dropbox and version control systems."
"When you run the notebook web application on your computer, notebook documents are just **files on your local filesystem with a `.ipynb` extension**. This allows you to use familiar workflows for organizing your notebooks into folders and sharing them with others."
Jonathan Frederic
11 years ago
