mirror/notebook
2
0
Fork 0
mirror of https://github.com/jupyter/notebook.git synced 2025-03-07 13:07:22 +08:00
Code Issues Packages Projects Releases Wiki Activity

Day 3 - Finishing pass over the notebooks.

Browse Source
This commit is contained in:
Jonathan Frederic 2015-06-01 10:28:31 -07:00
parent 4c008765fe
commit 75e53d915e
9 changed files with 50 additions and 698 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
examples/Notebook/Index.ipynb
View File

@ -4,14 +4,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"<img src=\"../images/ipython_logo.png\">"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Back to the main [Index](../Index.ipynb)"
"<img src=\"../images/jupyter_logo.png\">"
]
},
{
@ -25,7 +18,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The IPython Notebook is a web-based interactive computing system that enables users to author documents that include live code, narrative text, LaTeX equations, HTML, images and video. These documents contain a full record of a computation and its results and can be shared on email, [Dropbox](http://dropbox.com), version control systems (like git/[GitHub](http://github.com)) or [nbviewer.ipython.org](http://nbviewer.ipython.org)."
"The Jupyter Notebook is a web-based interactive computing system that enables users to author documents that include live code, narrative text, LaTeX equations, HTML, images and video. These documents contain a full record of a computation and its results and can be shared on email, [Dropbox](http://dropbox.com), version control systems (like git/[GitHub](http://github.com)) or [nbviewer.jupyter.org](http://nbviewer.jupyter.org)."
]
},
{
@ -39,15 +32,13 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"* [What is the IPython Notebook](What is the IPython Notebook.ipynb)\n",
"* [What is the Jupyter Notebook](What is the Jupyter Notebook.ipynb)\n",
"* [Notebook Basics](Notebook Basics.ipynb)\n",
"* [Running Code](Running Code.ipynb)\n",
"* [Working With Markdown Cells](Working With Markdown Cells.ipynb)\n",
"* [Configuring the Notebook and Server](Configuring the Notebook and Server.ipynb)\n",
"* [Custom Keyboard Shortcuts](Custom Keyboard Shortcuts.ipynb)\n",
"* [JavaScript Notebook Extensions](JavaScript Notebook Extensions.ipynb)\n",
"* [Converting Notebooks With nbconvert](Converting Notebooks With nbconvert.ipynb)\n",
"* [Using nbconvert as a Library](Using nbconvert as a Library.ipynb)"
"* [JavaScript Notebook Extensions](JavaScript Notebook Extensions.ipynb)"
]
},
{
@ -83,7 +74,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

43
examples/Notebook/JavaScript Notebook Extensions.ipynb
View File

@ -114,22 +114,11 @@
},
{
"cell_type": "code",
"execution_count": 13,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"data": {
"text/plain": [
"'/home/jon/.jupyter'"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"outputs": [],
"source": [
"import os.path\n",
"profile_dir = '~/.jupyter'\n",
@ -146,7 +135,7 @@
},
{
"cell_type": "code",
"execution_count": 14,
"execution_count": null,
"metadata": {
"collapsed": false
},
@ -158,19 +147,11 @@
},
{
"cell_type": "code",
"execution_count": 18,
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"You don't have a custom.js file\n"
]
}
],
"outputs": [],
"source": [
"# my custom js\n",
"if os.path.isfile(custom_js_path):\n",
@ -242,7 +223,7 @@
"foo": true
},
"source": [
"Create a dropdow elemement in the toolbar (DOM `IPython.toolbar.element`), you will need \n",
"Create a dropdow elemement in the toolbar (DOM `Jupyter.toolbar.element`), you will need \n",
"\n",
"- `IPython.notebook.set_autosave_interval(miliseconds)`\n",
"- know that 1min = 60 sec, and 1 sec = 1000 ms"
@ -328,7 +309,7 @@
"metadata": {},
"source": [
"```bash\n",
"$ cd ~/ipython/IPython/html/static/notebook/js/\n",
"$ cd ~/jupyter/notebook/notebook/static/notebook/js/\n",
"$ yuidoc . --server\n",
"warn: (yuidoc): Failed to extract port, setting to the default :3000\n",
"info: (yuidoc): Starting YUIDoc@0.3.45 using YUI@3.9.1 with NodeJS@0.10.15\n",
@ -362,7 +343,7 @@
"source": [
"By browsing the doc you will see that we have soem convenience methods that avoid to re-invent the UI everytime :\n",
"```javascript\n",
"IPython.toolbar.add_buttons_group([\n",
"Jupyter.toolbar.add_buttons_group([\n",
" {\n",
" 'label' : 'run qtconsole',\n",
" 'icon' : 'icon-terminal', // select your icon from \n",
@ -393,7 +374,7 @@
},
"source": [
"The most requested feature is generaly to be able to distinguish individual cell in th enotebook, or run specific action with them.\n",
"To do so, you can either use `IPython.notebook.get_selected_cell()`, or rely on `CellToolbar`. This allow you to register aset of action and graphical element that will be attached on individual cells."
"To do so, you can either use `Jupyter.notebook.get_selected_cell()`, or rely on `CellToolbar`. This allow you to register aset of action and graphical element that will be attached on individual cells."
]
},
{
@ -433,7 +414,7 @@
"outputs": [],
"source": [
"%%javascript\n",
"var CellToolbar = IPython.CellToolbar\n",
"var CellToolbar = Jupyter.CellToolbar\n",
"var toggle = function(div, cell) {\n",
" var button_container = $(div)\n",
"\n",
@ -483,8 +464,8 @@
"outputs": [],
"source": [
"%%javascript\n",
"IPython.CellToolbar.register_preset('Tutorial 1',['tuto.foo','default.rawedit'])\n",
"IPython.CellToolbar.register_preset('Tutorial 2',['slideshow.select','tuto.foo'])"
"Jupyter.CellToolbar.register_preset('Tutorial 1',['tuto.foo','default.rawedit'])\n",
"Jupyter.CellToolbar.register_preset('Tutorial 2',['slideshow.select','tuto.foo'])"
]
},
{

20
examples/Notebook/Notebook Basics.ipynb
View File

@ -18,7 +18,7 @@
"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."
"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."
]
},
{
@ -34,7 +34,7 @@
"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",
" jupyter 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",
@ -56,15 +56,15 @@
"\n",
"You can also specify the port manually:\n",
"\n",
" ipython notebook --port 9999\n",
" jupyter notebook --port 9999\n",
"\n",
"Or start notebook server without opening a web browser.\n",
"\n",
" ipython notebook --no-browser\n",
" jupyter 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"
" jupyter notebook --help"
]
},
{
@ -78,7 +78,7 @@
"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",
"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 Jupyter repository:\n",
"\n",
"<img src=\"images/dashboard_files_tab.png\" width=\"791px\"/>"
]
@ -156,7 +156,7 @@
"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."
"Starting with IPython 2.0, the Jupyter 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."
]
},
{
@ -244,7 +244,7 @@
"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."
"If you are running this notebook in a live session (not on http://nbviewer.jupyter.org) try selecting different cells and going between edit and command mode. Try typing into a cell."
]
},
{
@ -267,7 +267,7 @@
"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",
"The modal user interface of the Jupyter 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",
@ -305,7 +305,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

10
examples/Notebook/Running Code.ipynb
View File

@ -11,14 +11,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"First and foremost, the IPython Notebook is an interactive environment for writing and running code. IPython is capable of running code in a wide range of languages. However, this notebook, and the default kernel in IPython 2.0, runs Python code."
"First and foremost, the Jupyter Notebook is an interactive environment for writing and running code. The notebook is capable of running code in a wide range of languages. However, each notebook is associated with a single kernel. This notebook is associated with the IPython kernel, therefor runs Python code."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Code cells allow you to enter and run Python code"
"## Code cells allow you to enter and run code"
]
},
{
@ -64,14 +64,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Managing the IPython Kernel"
"## Managing the Kernel"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Code is run in a separate process called the IPython Kernel. The Kernel can be interrupted or restarted. Try running the following cell and then hit the <button class='btn btn-default btn-xs'><i class='icon-stop fa fa-stop'></i></button> button in the toolbar above."
"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 the <button class='btn btn-default btn-xs'><i class='icon-stop fa fa-stop'></i></button> button in the toolbar above."
]
},
{
@ -281,7 +281,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

8
examples/Notebook/Typesetting Equations.ipynb
View File

@ -4,7 +4,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The Markdown parser included in IPython is MathJax-aware. This means that you can freely mix in mathematical expressions using the [MathJax subset of Tex and LaTeX](http://docs.mathjax.org/en/latest/tex.html#tex-support). [Some examples from the MathJax site](http://www.mathjax.org/demos/tex-samples/) are reproduced below, as well as the Markdown+TeX source."
"The Markdown parser included in the Jupyter Notebook is MathJax-aware. This means that you can freely mix in mathematical expressions using the [MathJax subset of Tex and LaTeX](http://docs.mathjax.org/en/latest/tex.html#tex-support). [Some examples from the MathJax site](http://www.mathjax.org/demos/tex-samples/) are reproduced below, as well as the Markdown+TeX source."
]
},
{
@ -155,7 +155,7 @@
"\n",
"---\n",
"\n",
"Equation numbering and referencing will be available in a future version of IPython."
"Equation numbering and referencing will be available in a future version of the Jupyter notebook."
]
},
{
@ -183,7 +183,7 @@
"\n",
"---\n",
"\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 IPython notebook will accept this syntax on legacy notebooks. \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",
"```\n",
@ -263,7 +263,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

619
examples/Notebook/Using nbconvert as a Library.ipynb
View File

@ -1,619 +0,0 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Using nbconvert as a Library"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In this Notebook, you will be introduced to the programatic API of nbconvert and how it can be used in various contexts. \n",
"\n",
"One of [@jakevdp](https://github.com/jakevdp)'s great [blog posts](http://jakevdp.github.io/blog/2013/04/15/code-golf-in-python-sudoku/) will be used to demonstrate. This notebook will not focus on using the command line tool. The attentive reader will point-out that no data is read from or written to disk during the conversion process. Nbconvert has been designed to work in memory so that it works well in a database or web-based environement too."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Quick overview"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Credit, Jonathan Frederic (@jdfreder on github)\n",
"\n",
"<center>\n",
" ![nbca](images/nbconvert_arch.png)\n",
"</center>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The main principle of nbconvert is to instantiate an `Exporter` that controls\n",
"the pipeline through which notebooks are converted."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"First, download @jakevdp's notebook."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"import requests\n",
"response = requests.get('http://jakevdp.github.com/downloads/notebooks/XKCD_plots.ipynb')\n",
"response.text[0:60]+'...'"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you do not have `requests`, install it by running `pip install requests` (or if you don't have pip installed, you can find it on PYPI)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The response is a JSON string which represents an IPython notebook. Next, read the response using nbformat.\n",
"\n",
"Doing this will guarantee that the notebook structure is valid. Note that the in-memory format and on disk format are slightly different. In particual, on disk, multiline strings might be splitted into a list of strings."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython import nbformat\n",
"jake_notebook = nbformat.reads(response.text, as_version=4)\n",
"jake_notebook.cells[0]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The nbformat API returns a special dict. You don't need to worry about the details of the structure."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The nbconvert API exposes some basic exporters for common formats and defaults. You will start\n",
"by using one of them. First you will import it, then instantiate it using most of the defaults, and finally you will process notebook downloaded early."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython.config import Config\n",
"from IPython.nbconvert import HTMLExporter\n",
"\n",
"# The `basic` template is used here.\n",
"# Later you'll learn how to configure the exporter.\n",
"html_exporter = HTMLExporter(config=Config({'HTMLExporter':{'default_template':'basic'}}))"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"(body, resources) = html_exporter.from_notebook_node(jake_notebook)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The exporter returns a tuple containing the body of the converted notebook, raw HTML in this case, as well as a resources dict. The resource dict contains (among many things) the extracted PNG, JPG [...etc] from the notebook when applicable. The basic HTML exporter leaves the figures as embeded base64, but you can configure it to extract the figures. So for now, the resource dict **should** be mostly empty, except for a key containing CSS and a few others whose content will be obvious.\n",
"\n",
"`Exporter`s are stateless, so you won't be able to extract any usefull information beyond their configuration from them. You can re-use an exporter instance to convert another notebook. Each exporter exposes, for convenience, a `from_file` and `from_filename` method."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"print([key for key in resources ])\n",
"print(resources['metadata'])\n",
"print(resources['output_extension'])\n",
"# print resources['inlining'] # Too long to be shown"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"# Part of the body, here the first Heading\n",
"start = body.index('<h1 id', )\n",
"print(body[:400]+'...')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you understand HTML, you'll notice that some common tags are ommited, like the `body` tag. Those tags are included in the default `HtmlExporter`, which is what would have been constructed if no Config object was passed into it."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Extracting Figures"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When exporting you may want to extract the base64 encoded figures as files, this is by default what the `RstExporter` does (as seen below)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython.nbconvert import RSTExporter\n",
"\n",
"rst_exporter = RSTExporter()\n",
"\n",
"(body,resources) = rst_exporter.from_notebook_node(jake_notebook)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"print(body[:970]+'...')\n",
"print('[.....]')\n",
"print(body[800:1200]+'...')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Notice that base64 images are not embeded, but instead there are file name like strings. The strings actually are (configurable) keys that map to the binary data in the resources dict.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note, if you write an RST Plugin, you are responsible for writing all the files to the disk (or uploading, etc...) in the right location. Of course, the naming scheme is configurable."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As an exercise, this notebook will show you how to get one of those images."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"list(resources['outputs'])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"There are 5 extracted binary figures, all `png`s, but they could have been `svg`s which then wouldn't appear in the binary sub dict. Keep in mind that objects with multiple reprs will have every repr stored in the notebook avaliable for conversion. \n",
"\n",
"Hence if the object provides `_repr_javascript_`, `_repr_latex_`, and `_repr_png_`, you will be able to determine, at conversion time, which representaition is most appropriate. You could even show all of the representaitions of an object in a single export, it's up to you. Doing so would require a little more involvement on your part and a custom Jinja template.\n",
"\n",
"Back to the task of extracting an image, the Image display object can be used to display one of the images (as seen below)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython.display import Image\n",
"Image(data=resources['outputs']['output_3_0.png'],format='png')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This image is being rendered without reading or writing to the disk."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Extracting figures with HTML Exporter ?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Use case:\n",
"\n",
"> I write an [awesome blog](http://jakevdp.github.io/) using IPython notebooks converted to HTML, and I want the images to be cached. Having one html file with all of the images base64 encoded inside it is nice when sharing with a coworker, but for a website, not so much. I need an HTML exporter, and I want it to extract the figures!"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Some theory"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The process of converting a notebook to a another format with happens in a few steps:\n",
"\n",
" - Retrieve the notebook and it's accompanying resource (you are responsible for this).\n",
" - Feed them into the exporter, which:\n",
" - Sequentially feeds them into an array of `Preprocessors`. Preprocessors only act on the **structure** of the notebook, and have unrestricted access to it. \n",
" - Feeds the notebook into the Jinja templating engine.\n",
" - The template is configured (you can change which one is used).\n",
" - Templates make use of configurable macros called `filters`.\n",
" - The exporter returns the converted notebook and other relevant resources as a tuple.\n",
" - You write the data to the disk, or elsewhere (you are responsible for this too)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You can use `Preprocessors` to accomplish the task at hand. IPython has preprocessors built in which you can use. One of them, the `ExtractOutputPreprocessor` is responsible for crawling the notebook, finding all of the figures, and putting them into the resources directory, as well as choosing the key (i.e. `filename_xx_y.extension`) that can replace the figure inside the template.\n",
"\n",
"The `ExtractOutputPreprocessor` is special because it's available in all of the `Exporter`s, and is just disabled in some by default."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"# 3rd one should be <ExtractOutputPreprocessor>\n",
"html_exporter._preprocessors"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Use the IPython configuration/Traitlets system to enable it. If you have already set IPython configuration options, this system is familiar to you. Configuration options will always of the form:\n",
"\n",
" ClassName.attribute_name = value\n",
" \n",
"You can create a configuration object a couple of different ways. Everytime you launch IPython, configuration objects are created from reading config files in your profile directory. Instead of writing a config file, you can also do it programatically using a dictionary. The following creates a config object, that enables the figure extracter, and passes it to an `HTMLExporter`. The output is compared to an `HTMLExporter` without the config object."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython.config import Config\n",
"\n",
"c = Config({\n",
" 'ExtractOutputPreprocessor':{'enabled':True}\n",
" })\n",
"\n",
"exportHTML = HTMLExporter()\n",
"exportHTML_and_figs = HTMLExporter(config=c)\n",
"\n",
"(_, resources) = exportHTML.from_notebook_node(jake_notebook)\n",
"(_, resources_with_fig) = exportHTML_and_figs.from_notebook_node(jake_notebook)\n",
"\n",
"print('resources without the \"figures\" key:')\n",
"print(list(resources))\n",
"\n",
"print('')\n",
"print('ditto, notice that there\\'s one more field:')\n",
"print(list(resources_with_fig))\n",
"list(resources_with_fig['outputs'])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Custom Preprocessor"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"There are an endless number of transformations that you may want to apply to a notebook. This is why we provide a way to register your own preprocessors that will be applied to the notebook after the default ones.\n",
"\n",
"To do so, you'll have to pass an ordered list of `Preprocessor`s to the `Exporter`'s constructor. \n",
"\n",
"For simple cell-by-cell transformations, `Preprocessor` can be created using a decorator. For more complex operations, you need to subclass `Preprocessor` and define a `call` method (as seen below).\n",
"\n",
"All transforers have a flag that allows you to enable and disable them via a configuration object."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython.nbconvert.preprocessors import Preprocessor\n",
"import IPython.config\n",
"print(\"Four relevant docstring\")\n",
"print('=============================')\n",
"print(Preprocessor.__doc__)\n",
"print('=============================')\n",
"print(Preprocessor.preprocess.__doc__)\n",
"print('=============================')\n",
"print(Preprocessor.preprocess_cell.__doc__)\n",
"print('=============================')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Example"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following demonstration was requested in [an IPython GitHub issue](https://github.com/ipython/nbconvert/pull/137#issuecomment-18658235), the ability to exclude a cell by index. \n",
"\n",
"Inject cells is similar, and won't be covered here. If you want to inject static content at the beginning/end of a notebook, use a custom template."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from traitlets import Integer"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"class PelicanSubCell(Preprocessor):\n",
" \"\"\"A Pelican specific preprocessor to remove some of the cells of a notebook\"\"\"\n",
" \n",
" # I could also read the cells from nbc.metadata.pelican is someone wrote a JS extension\n",
" # But I'll stay with configurable value. \n",
" start = Integer(0, config=True, help=\"first cell of notebook to be converted\")\n",
" end = Integer(-1, config=True, help=\"last cell of notebook to be converted\")\n",
" \n",
" def preprocess(self, nb, resources):\n",
"\n",
" #nbc = deepcopy(nb)\n",
" nbc = nb\n",
" # don't print in real preprocessor !!!\n",
" print(\"I'll keep only cells from \", self.start, \"to \", self.end, \"\\n\\n\")\n",
" nbc.cells = nb.cells[self.start:self.end] \n",
" return nbc, resources"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"# I create this on the fly, but this could be loaded from a DB, and config object support merging...\n",
"c = Config()\n",
"c.PelicanSubCell.enabled = True\n",
"c.PelicanSubCell.start = 4\n",
"c.PelicanSubCell.end = 6"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here a Pelican exporter is created that takes `PelicanSubCell` preprocessors and a `config` object as parameters. This may seem redundant, but with the configuration system you can register an inactive preprocessor on all of the exporters and activate it from config files or the command line. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"pelican = RSTExporter(preprocessors=[PelicanSubCell], config=c)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"print(pelican.from_notebook_node(jake_notebook)[0])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Programatically make templates"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from jinja2 import DictLoader\n",
"\n",
"dl = DictLoader({'full.tpl': \n",
"\"\"\"\n",
"{%- extends 'basic.tpl' -%} \n",
"\n",
"{% block footer %}\n",
"FOOOOOOOOTEEEEER\n",
"{% endblock footer %}\n",
"\"\"\"})\n",
"\n",
"\n",
"exportHTML = HTMLExporter(extra_loaders=[dl])\n",
"(body,resources) = exportHTML.from_notebook_node(jake_notebook)\n",
"for l in body.split('\\n')[-4:]:\n",
" print(l)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Real World Use"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"@jakevdp uses Pelican and IPython Notebook to blog. Pelican [will use](https://github.com/getpelican/pelican-plugins/pull/21) nbconvert programatically to generate blog post. Have a look a [Pythonic Preambulations](http://jakevdp.github.io/) for Jake's blog post."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"@damianavila wrote the Nicholas Plugin to [write blog post as Notebooks](http://www.damian.oquanta.info/posts/one-line-deployment-of-your-site-to-gh-pages.html) and is developping a js-extension to publish notebooks via one click from the web app."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<center>\n",
"<blockquote class=\"twitter-tweet\"><p>As <a href=\"https://twitter.com/Mbussonn\">@Mbussonn</a> requested... easieeeeer! Deploy your Nikola site with just a click in the IPython notebook! <a href=\"http://t.co/860sJunZvj\">http://t.co/860sJunZvj</a> cc <a href=\"https://twitter.com/ralsina\">@ralsina</a></p>&mdash; Damián Avila (@damian_avila) <a href=\"https://twitter.com/damian_avila/statuses/370306057828335616\">August 21, 2013</a></blockquote>\n",
"</center>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### A few gotchas"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Jinja blocks use `{% %}`by default which does not play nicely with $\\LaTeX$, hence thoses are replaced by `((* *))` in latex templates."
]
}
],
"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
}

21
examples/Notebook/What is the IPython Notebook.ipynb → examples/Notebook/What is the Jupyter Notebook.ipynb
View File

@ -8,7 +8,7 @@
}
},
"source": [
"# What is the IPython Notebook?"
"# What is the Jupyter Notebook?"
]
},
{
@ -22,7 +22,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The IPython Notebook is an **interactive computing environment** that enables users to author notebook documents that include: \n",
"The Jupyter Notebook is an **interactive computing environment** that enables users to author notebook documents that include: \n",
"- Live code\n",
"- Interactive widgets\n",
"- Plots\n",
@ -31,7 +31,7 @@
"- Images\n",
"- Video\n",
"\n",
"These documents provide a **complete and self-contained record of a computation** that can be converted to various formats and shared with others using email, [Dropbox](http://dropbox.com), version control systems (like git/[GitHub](http://github.com)) or [nbviewer.ipython.org](http://nbviewer.ipython.org)."
"These documents provide a **complete and self-contained record of a computation** that can be converted to various formats and shared with others using email, [Dropbox](http://dropbox.com), version control systems (like git/[GitHub](http://github.com)) or [nbviewer.jupyter.org](http://nbviewer.jupyter.org)."
]
},
{
@ -49,7 +49,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The IPython Notebook combines three components:\n",
"The Jupyter Notebook combines three components:\n",
"\n",
"* **The notebook web application**: An interactive web application for writing and running code interactively and authoring notebook documents.\n",
"* **Kernels**: Separate processes started by the notebook web application that runs users' code in a given language and returns output back to the notebook web application. The kernel also handles things like computations for interactive widgets, tab completion and introspection. \n",
@ -80,8 +80,7 @@
"* Create and use **interactive JavaScript wigets**, which bind interactive user interface controls and visualizations to reactive kernel side computations.\n",
"* Author **narrative text** using the [Markdown](https://daringfireball.net/projects/markdown/) markup language.\n",
"* Build **hierarchical documents** that are organized into sections with different levels of headings.\n",
"* Include mathematical equations using **LaTeX syntax in Markdown**, which are rendered in-browser by [MathJax](http://www.mathjax.org/).\n",
"* Start **parallel computing** clusters that work with IPython's interactive parallel computing libraries `IPython.parallel`."
"* Include mathematical equations using **LaTeX syntax in Markdown**, which are rendered in-browser by [MathJax](http://www.mathjax.org/)."
]
},
{
@ -99,7 +98,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Through IPython's kernel and messaging architecture, the Notebook allows code to be run in a range of different programming languages. For each notebook document that a user opens, the web application starts a kernel that runs the code for that notebook. Each kernel is capable of running code in a single programming language and there are kernels available in the following languages:\n",
"Through Jupyter's kernel and messaging architecture, the Notebook allows code to be run in a range of different programming languages. For each notebook document that a user opens, the web application starts a kernel that runs the code for that notebook. Each kernel is capable of running code in a single programming language and there are kernels available in the following languages:\n",
"\n",
"* Python(https://github.com/ipython/ipython)\n",
"* Julia (https://github.com/JuliaLang/IJulia.jl)\n",
@ -110,7 +109,7 @@
"* node.js (https://gist.github.com/Carreau/4279371)\n",
"* Go (https://github.com/takluyver/igo)\n",
"\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",
"The default kernel runs Python code. The notebook 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.\""
]
@ -153,9 +152,9 @@
"\n",
"Internally, notebook documents are **[JSON](http://en.wikipedia.org/wiki/JSON) data** with **binary values [base64](http://en.wikipedia.org/wiki/Base64)** encoded. This allows them to be **read and manipulated programmatically** by any programming language. Because JSON is a text format, notebook documents are version control friendly.\n",
"\n",
"**Notebooks can be exported** to different static formats including HTML, reStructeredText, LaTeX, PDF, and slide shows ([reveal.js](http://lab.hakim.se/reveal-js/#/)) using IPython's `nbconvert` utility.\n",
"**Notebooks can be exported** to different static formats including HTML, reStructeredText, LaTeX, PDF, and slide shows ([reveal.js](http://lab.hakim.se/reveal-js/#/)) using Jupyter's `nbconvert` utility.\n",
"\n",
"Furthermore, any notebook document available from a **public URL on or GitHub can be shared** via [nbviewer](http://nbviewer.ipython.org). This service loads the notebook document from the URL and renders it as a static web page. The resulting web page may thus be shared with others **without their needing to install IPython**."
"Furthermore, any notebook document available from a **public URL on or GitHub can be shared** via [nbviewer](http://nbviewer.ipython.org). This service loads the notebook document from the URL and renders it as a static web page. The resulting web page may thus be shared with others **without their needing to install the Jupyter Notebook**."
]
}
],
@ -175,7 +174,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

8
examples/Notebook/Working With Markdown Cells.ipynb
View File

@ -11,7 +11,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Text can be added to IPython Notebooks using Markdown cells. Markdown is a popular markup language that is a superset of HTML. Its specification can be found here:\n",
"Text can be added to Jupyter Notebooks using Markdown cells. Markdown is a popular markup language that is a superset of HTML. Its specification can be found here:\n",
"\n",
"<http://daringfireball.net/projects/markdown/>"
]
@ -98,7 +98,7 @@
"source": [
"And shorthand for links:\n",
"\n",
"[IPython's website](http://ipython.org)"
"[Jupyter's website](http://jupyter.org)"
]
},
{
@ -285,7 +285,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that this means that the IPython notebook server also acts as a generic file server\n",
"Note that this means that the Jupyter notebook server also acts as a generic file server\n",
"for files inside the same tree as your notebooks. Access is not granted outside the\n",
"notebook folder so you have strict control over what files are visible, but for this\n",
"reason it is highly recommended that you do not run the notebook server with a notebook\n",
@ -312,7 +312,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

BIN
examples/images/jupyter_logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 KiB