mirror/notebook
2
0
Fork 0
mirror of https://github.com/jupyter/notebook.git synced 2024-12-21 04:10:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #124 from jdfreder/docs

Browse Source 
Docs
This commit is contained in:
Matthias Bussonnier 2015-06-05 10:33:42 -07:00
commit 9a9a74908b
26 changed files with 225 additions and 1782 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -4,6 +4,7 @@ dist
_build
docs/man/*.gz
docs/source/api/generated
docs/source/config.rst
docs/gh-pages
notebook/static/components
notebook/static/style/*.min.css*

7
docs/Makefile
View File

@ -50,12 +50,17 @@ help:
clean:
rm -rf $(BUILDDIR)/*
rm -rf source/config.rst
html:
html: source/config.rst
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
source/config.rst:
python3 autogen_config.py
@echo "Created docs for config options"
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo

44
docs/autogen_config.py Normal file
View File

@ -0,0 +1,44 @@
#!/usr/bin/env python
import os
from notebook.notebookapp import NotebookApp
header = """\
.. _config:
Config
======
The notebook server can be run with a variety of command line arguments.
A list of available options can be found below in the :ref:`options section
<options>`.
Defaults for these options can also be set by creating a file named
``jupyter_notebook_config.py`` in your Jupyter folder. The Jupyter
folder is in your home directory, ``~/.jupyter``.
To create a ``jupyter_notebook_config.py`` file, with all the defaults
commented out, you can use the following command line::
$ jupyter notebook --generate-config
.. _options:
Options
-------
This list of options can be generated by running the following and hitting
enter::
$ jupyter notebook --help
"""
try:
destination = os.path.join(os.path.dirname(__file__), 'source/config.rst')
except:
destination = os.path.join(os.getcwd(), 'config.rst')
with open(destination, 'w') as f:
f.write(header)
f.write(NotebookApp().document_config_options())

2
docs/jsdoc_config.json
View File

@ -8,7 +8,7 @@
],
"source": {
"include": [
"../IPython/html/static/notebook/js/notebook.js"
"../notebook/static/notebook/js/notebook.js"
]
},
"tags": {

9
docs/requirements.txt Normal file
View File

@ -0,0 +1,9 @@
jinja2
tornado
-e git+https://github.com/ipython/ipython_genutils.git#egg=ipython_genutils
-e git+https://github.com/ipython/traitlets.git#egg=traitlets
-e git+https://github.com/jupyter/jupyter_core.git#egg=jupyter_core
-e git+https://github.com/jupyter/nbformat.git#egg=nbformat
-e git+https://github.com/jupyter/jupyter_client.git#egg=jupyter_client
-e git+https://github.com/ipython/ipython.git#egg=ipython
-e git+https://github.com/ipython/ipykernel.git#egg=ipykernel

15
docs/source/conf.py
View File

@ -20,7 +20,14 @@ import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../..'))
if os.environ.get('READTHEDOCS', ''):
# Readthedocs doesn't run our Makefile, so we do this to force it to generate
# the config docs.
with open('../autogen_config.py') as f:
exec(compile(f.read(), '../autogen_config.py', 'exec'), {})
# -- General configuration ------------------------------------------------
@ -113,7 +120,7 @@ todo_include_todos = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -289,5 +296,7 @@ texinfo_documents = [
#texinfo_no_detailmenu = False
intersphinx_mapping = {
'ipython': ('http://ipython.org/ipython-doc/dev/', None)
'ipython': ('http://ipython.org/ipython-doc/dev/', None),
'nbconvert': ('http://nbconvert.readthedocs.org/en/latest/', None),
'nbformat': ('http://nbformat.readthedocs.org/en/latest/', None)
}

6
docs/source/index.rst
View File

@ -1,14 +1,12 @@
====================
The IPython notebook
The Jupyter notebook
====================
.. toctree::
:maxdepth: 2
notebook
nbformat
nbconvert
config
public_server
security
development

18
docs/source/links.txt
View File

@ -16,23 +16,23 @@
NOTE: Some of these were taken from the nipy links compendium.
.. Main IPython links
.. Main Jupyter notebook links
.. _Basic Output: notebook_p2_
.. _notebook_p2: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%202%20-%20Basic%20Output.ipynb
.. _Notebook Basics: notebook_p2_
.. _notebook_p2: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/Notebook/Notebook%20Basics.ipynb
.. _Running Code in the IPython Notebook: notebook_p1_
.. _notebook_p1: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%25201%2520-%2520Running%2520Code.ipynb
.. _Running Code in the Jupyter Notebook: notebook_p1_
.. _notebook_p1: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/Notebook/Running%20Code.ipynb
.. Other python projects
.. _matplotlib: http://matplotlib.org
.. _nbviewer: http://nbviewer.ipython.org
.. _nbviewer: http://nbviewer.jupyter.org
.. Other tools and projects
.. _Markdown: http://daringfireball.net/projects/markdown/syntax
.. _Rich Display System: notebook_p5_
.. _notebook_p5: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%205%20-%20Rich%20Display%20System.ipynb
.. _Rich Output: notebook_p5_
.. _notebook_p5: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/IPython%20Kernel/Rich%20Output.ipynb
.. _Plotting with Matplotlib: notebook_p3_
.. _notebook_p3: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%203%20-%20Plotting%20with%20Matplotlib.ipynb
.. _notebook_p3: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/IPython%20Kernel/Plotting%20in%20the%20Notebook.ipynb

168
docs/source/nbconvert.rst
View File

@ -1,168 +0,0 @@
.. _nbconvert:
Converting notebooks to other formats
=====================================
Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which
allows you to convert an ``.ipynb`` notebook document file into various static
formats.
Currently, ``nbconvert`` is provided as a command line tool, run as a script
using IPython. A direct export capability from within the
IPython Notebook web app is planned.
The command-line syntax to run the ``nbconvert`` script is::
$ ipython nbconvert --to FORMAT notebook.ipynb
This will convert the IPython document file ``notebook.ipynb`` into the output
format given by the ``FORMAT`` string.
The default output format is html, for which the ``--to`` argument may be
omitted::
$ ipython nbconvert notebook.ipynb
IPython provides a few templates for some output formats, and these can be
specified via an additional ``--template`` argument.
The currently supported export formats are:
* ``--to html``
- ``--template full`` (default)
A full static HTML render of the notebook.
This looks very similar to the interactive view.
- ``--template basic``
Simplified HTML, useful for embedding in webpages, blogs, etc.
This excludes HTML headers.
* ``--to latex``
Latex export. This generates ``NOTEBOOK_NAME.tex`` file,
ready for export.
- ``--template article`` (default)
Latex article, derived from Sphinx's howto template.
- ``--template report``
Latex report, providing a table of contents and chapters.
- ``--template basic``
Very basic latex output - mainly meant as a starting point for custom templates.
* ``--to pdf``
Generates a PDF via latex. Supports the same templates as ``--to latex``.
* ``--to slides``
This generates a Reveal.js HTML slideshow.
It must be served by an HTTP server. The easiest way to do this is adding
``--post serve`` on the command-line. The ``serve`` post-processor proxies
Reveal.js requests to a CDN if no local Reveal.js library is present.
To make slides that don't require an internet connection, just place the
Reveal.js library in the same directory where your_talk.slides.html is located,
or point to another directory using the ``--reveal-prefix`` alias.
* ``--to markdown``
Simple markdown output. Markdown cells are unaffected,
and code cells indented 4 spaces.
* ``--to rst``
Basic reStructuredText output. Useful as a starting point for embedding notebooks
in Sphinx docs.
* ``--to script``
Convert a notebook to an executable script.
This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
If there were any magics in an IPython notebook, this may only be executable from
an IPython session.
* ``--to notebook``
.. versionadded:: 3.0
This doesn't convert a notebook to a different format *per se*,
instead it allows the running of nbconvert preprocessors on a notebook,
and/or conversion to other notebook formats. For example::
ipython nbconvert --to notebook --execute mynotebook.ipynb
will open the notebook, execute it, capture new output, and save the result in
:file:`mynotebook.nbconvert.ipynb`.
::
ipython nbconvert --to notebook --nbformat 3 mynotebook
will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
in version 3 of the :ref:`notebook format <nbformat>`.
If you want to convert a notebook in-place,
you can specify the ouptut file to be the same as the input file::
ipython nbconvert --to notebook mynb --output mynb
Be careful with that, since it will replace the input file.
.. note::
nbconvert uses pandoc_ to convert between various markup languages,
so pandoc is a dependency when converting to latex or reStructuredText.
.. _pandoc: http://johnmacfarlane.net/pandoc/
The output file created by ``nbconvert`` will have the same base name as
the notebook and will be placed in the current working directory. Any
supporting files (graphics, etc) will be placed in a new directory with the
same base name as the notebook, suffixed with ``_files``::
$ ipython nbconvert notebook.ipynb
$ ls
notebook.ipynb notebook.html notebook_files/
For simple single-file output, such as html, markdown, etc.,
the output may be sent to standard output with::
$ ipython nbconvert --to markdown notebook.ipynb --stdout
Multiple notebooks can be specified from the command line::
$ ipython nbconvert notebook*.ipynb
$ ipython nbconvert notebook1.ipynb notebook2.ipynb
or via a list in a configuration file, say ``mycfg.py``, containing the text::
c = get_config()
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
and using the command::
$ ipython nbconvert --config mycfg.py
LaTeX citations
---------------
``nbconvert`` now has support for LaTeX citations. With this capability you
can:
* Manage citations using BibTeX.
* Cite those citations in Markdown cells using HTML data attributes.
* Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.
For an example of how this works, please see the citations example in
the nbconvert-examples_ repository.
.. _nbconvert-examples: https://github.com/ipython/nbconvert-examples

358
docs/source/nbformat.rst
View File

@ -1,358 +0,0 @@
.. _nbformat:
===========================
The Jupyter Notebook Format
===========================
Introduction
============
Jupyter (né IPython) notebook files are simple JSON documents,
containing text, source code, rich media output, and metadata.
each segment of the document is stored in a cell.
Some general points about the notebook format:
.. note::
*All* metadata fields are optional.
While the type and values of some metadata are defined,
no metadata values are required to be defined.
Top-level structure
===================
At the highest level, a Jupyter notebook is a dictionary with a few keys:
- metadata (dict)
- nbformat (int)
- nbformat_minor (int)
- cells (list)
.. sourcecode:: python
{
"metadata" : {
"signature": "hex-digest", # used for authenticating unsafe outputs on load
"kernel_info": {
# if kernel_info is defined, its name field is required.
"name" : "the name of the kernel"
},
"language_info": {
# if language_info is defined, its name field is required.
"name" : "the programming language of the kernel",
"version": "the version of the language",
"codemirror_mode": "The name of the codemirror mode to use [optional]"
}
},
"nbformat": 4,
"nbformat_minor": 0,
"cells" : [
# list of cell dictionaries, see below
],
}
Some fields, such as code input and text output, are characteristically multi-line strings.
When these fields are written to disk, they **may** be written as a list of strings,
which should be joined with ``''`` when reading back into memory.
In programmatic APIs for working with notebooks (Python, Javascript),
these are always re-joined into the original multi-line string.
If you intend to work with notebook files directly,
you must allow multi-line string fields to be either a string or list of strings.
Cell Types
==========
There are a few basic cell types for encapsulating code and text.
All cells have the following basic structure:
.. sourcecode:: python
{
"cell_type" : "name",
"metadata" : {},
"source" : "single string or [list, of, strings]",
}
Markdown cells
--------------
Markdown cells are used for body-text, and contain markdown,
as defined in `GitHub-flavored markdown`_, and implemented in marked_.
.. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown
.. _marked: https://github.com/chjj/marked
.. sourcecode:: python
{
"cell_type" : "markdown",
"metadata" : {},
"source" : ["some *markdown*"],
}
.. versionchanged:: nbformat 4.0
Heading cells have been removed, in favor of simple headings in markdown.
Code cells
----------
Code cells are the primary content of Jupyter notebooks.
They contain source code in the language of the document's associated kernel,
and a list of outputs associated with executing that code.
They also have an execution_count, which must be an integer or ``null``.
.. sourcecode:: python
{
"cell_type" : "code",
"execution_count": 1, # integer or null
"metadata" : {
"collapsed" : True, # whether the output of the cell is collapsed
"autoscroll": False, # any of true, false or "auto"
},
"source" : ["some code"],
"outputs": [{
# list of output dicts (described below)
"output_type": "stream",
...
}],
}
.. versionchanged:: nbformat 4.0
``input`` was renamed to ``source``, for consistency among cell types.
.. versionchanged:: nbformat 4.0
``prompt_number`` renamed to ``execution_count``
Code cell outputs
-----------------
A code cell can have a variety of outputs (stream data or rich mime-type output).
These correspond to :ref:`messages <messaging>` produced as a result of executing the cell.
All outputs have an ``output_type`` field,
which is a string defining what type of output it is.
stream output
*************
.. sourcecode:: python
{
"output_type" : "stream",
"name" : "stdout", # or stderr
"text" : ["multiline stream text"],
}
.. versionchanged:: nbformat 4.0
The keys ``stream`` key was changed to ``name`` to match
the stream message.
display_data
************
Rich display outputs, as created by ``display_data`` messages,
contain data keyed by mime-type. This is often called a mime-bundle,
and shows up in various locations in the notebook format and message spec.
The metadata of these messages may be keyed by mime-type as well.
.. sourcecode:: python
{
"output_type" : "display_data",
"data" : {
"text/plain" : ["multiline text data"],
"image/png": ["base64-encoded-png-data"],
"application/json": {
# JSON data is included as-is
"json": "data",
},
},
"metadata" : {
"image/png": {
"width": 640,
"height": 480,
},
},
}
.. versionchanged:: nbformat 4.0
``application/json`` output is no longer double-serialized into a string.
.. versionchanged:: nbformat 4.0
mime-types are used for keys, instead of a combination of short names (``text``)
and mime-types, and are stored in a ``data`` key, rather than the top-level.
i.e. ``output.data['image/png']`` instead of ``output.png``.
execute_result
**************
Results of executing a cell (as created by ``displayhook`` in Python)
are stored in ``execute_result`` outputs.
`execute_result` outputs are identical to ``display_data``,
adding only a ``execution_count`` field, which must be an integer.
.. sourcecode:: python
{
"output_type" : "execute_result",
"execution_count": 42,
"data" : {
"text/plain" : ["multiline text data"],
"image/png": ["base64-encoded-png-data"],
"application/json": {
# JSON data is included as-is
"json": "data",
},
},
"metadata" : {
"image/png": {
"width": 640,
"height": 480,
},
},
}
.. versionchanged:: nbformat 4.0
``pyout`` renamed to ``execute_result``
.. versionchanged:: nbformat 4.0
``prompt_number`` renamed to ``execution_count``
error
*****
Failed execution may show a traceback
.. sourcecode:: python
{
'ename' : str, # Exception name, as a string
'evalue' : str, # Exception value, as a string
# The traceback will contain a list of frames,
# represented each as a string.
'traceback' : list,
}
.. versionchanged:: nbformat 4.0
``pyerr`` renamed to ``error``
.. _raw nbconvert cells:
Raw NBConvert cells
-------------------
A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output.
For example, this cell could include raw LaTeX for nbconvert to pdf via latex,
or restructured text for use in Sphinx documentation.
The notebook authoring environment does not render raw cells.
The only logic in a raw cell is the `format` metadata field.
If defined, it specifies which nbconvert output format is the intended target
for the raw cell. When outputting to any other format,
the raw cell's contents will be excluded.
In the default case when this value is undefined,
a raw cell's contents will be included in any nbconvert output,
regardless of format.
.. sourcecode:: python
{
"cell_type" : "raw",
"metadata" : {
# the mime-type of the target nbconvert format.
# nbconvert to formats other than this will exclude this cell.
"format" : "mime/type"
},
"source" : ["some nbformat mime-type data"]
}
Backward-compatible changes
===========================
The notebook format is an evolving format. When backward-compatible changes are made,
the notebook format minor version is incremented. When backward-incompatible changes are made,
the major version is incremented.
As of nbformat 4.x, backward-compatible changes include:
- new fields in any dictionary (notebook, cell, output, metadata, etc.)
- new cell types
- new output types
New cell or output types will not be rendered in versions that do not recognize them,
but they will be preserved.
Metadata
========
Metadata is a place that you can put arbitrary JSONable information about
your notebook, cell, or output. Because it is a shared namespace,
any custom metadata should use a sufficiently unique namespace,
such as `metadata.kaylees_md.foo = "bar"`.
Metadata fields officially defined for Jupyter notebooks are listed here:
Notebook metadata
-----------------
The following metadata keys are defined at the notebook level:
=========== =============== ==============
Key Value Interpretation
=========== =============== ==============
kernelspec dict A :ref:`kernel specification <kernelspecs>`
signature str A hashed :ref:`signature <notebook_security>` of the notebook
=========== =============== ==============
Cell metadata
-------------
The following metadata keys are defined at the cell level:
=========== =============== ==============
Key Value Interpretation
=========== =============== ==============
collapsed bool Whether the cell's output container should be collapsed
autoscroll bool or 'auto' Whether the cell's output is scrolled, unscrolled, or autoscrolled
deletable bool If False, prevent deletion of the cell
format 'mime/type' The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>`
name str A name for the cell. Should be unique
tags list of str A list of string tags on the cell. Commas are not allowed in a tag
=========== =============== ==============
Output metadata
---------------
The following metadata keys are defined for code cell outputs:
=========== =============== ==============
Key Value Interpretation
=========== =============== ==============
isolated bool Whether the output should be isolated into an IFrame
=========== =============== ==============

151
docs/source/notebook.rst
View File

@ -1,6 +1,6 @@
.. _htmlnotebook:
The IPython Notebook
The Jupyter Notebook
====================
Introduction
@ -9,7 +9,7 @@ Introduction
The notebook extends the console-based approach to interactive computing in
a qualitatively new direction, providing a web-based application suitable for
capturing the whole computation process: developing, documenting, and
executing code, as well as communicating the results. The IPython notebook
executing code, as well as communicating the results. The Jupyter notebook
combines two components:
**A web application**: a browser-based tool for interactive authoring of
@ -65,22 +65,22 @@ colleagues.
Notebooks may be exported to a range of static formats, including HTML (for
example, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, via
the new :ref:`nbconvert <nbconvert>` command.
the new :ref:`nbconvert <nbconvert:index>` command.
Furthermore, any ``.ipynb`` notebook document available from a public
URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
URL can be shared via the `Jupyter Notebook Viewer <nbviewer>`_ (nbviewer_).
This service loads the notebook document from the URL and renders it as a
static web page. The results may thus be shared with a colleague, or as a
public blog post, without other users needing to install IPython themselves.
In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
so you can do your own static conversions with nbconvert, without relying on
nbviewer.
public blog post, without other users needing to install the Jupyter notebook
themselves. In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert:index>` as
a web service, so you can do your own static conversions with nbconvert,
without relying on nbviewer.
.. seealso::
:ref:`Details on the notebook JSON file format <nbformat>`
:ref:`Details on the notebook JSON file format <nbformat:format_description>`
Starting the notebook server
@ -89,13 +89,13 @@ Starting the notebook server
You can start running a notebook server from the command line using the
following command::
ipython notebook
jupyter notebook
This will print some information about the notebook server in your console,
and open a web browser to the URL of the web application (by default,
``http://127.0.0.1:8888``).
The landing page of the IPython notebook web application, the **dashboard**,
The landing page of the Jupyter notebook web application, the **dashboard**,
shows the notebooks currently available in the notebook directory (by default,
the directory from which the notebook server was started).
@ -105,7 +105,7 @@ and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
into the notebook list area.
When starting a notebook server from the command line, you can also open a
particular notebook directly, bypassing the dashboard, with ``ipython notebook
particular notebook directly, bypassing the dashboard, with ``jupyter notebook
my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
given.
@ -225,7 +225,7 @@ example, in the ``pandas`` data analysis package). This is known as IPython's
`Basic Output`_ example notebook
`Rich Display System`_ example notebook
`Rich Output`_ example notebook
Markdown cells
~~~~~~~~~~~~~~
@ -267,7 +267,7 @@ Raw cells
*Raw* cells provide a place in which you can write *output* directly.
Raw cells are not evaluated by the notebook.
When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
When passed through :ref:`nbconvert <nbconvert:index>`, raw cells arrive in the
destination format unmodified. For example, this allows you to type full LaTeX
into a raw cell, which will only be rendered by LaTeX after conversion by
nbconvert.
@ -312,9 +312,9 @@ content of markdown cells have been inserted as comments.
.. seealso::
`Running Code in the IPython Notebook`_ example notebook
`Running Code in the Jupyter Notebook`_ example notebook
`Basic Output`_ example notebook
`Notebook Basics`_ example notebook
:ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
@ -358,80 +358,18 @@ For the full list of available shortcuts, click :guilabel:`Help`,
Plotting
--------
One major feature of the notebook is the ability to display plots that are the
output of running code cells. IPython is designed to work seamlessly with the
matplotlib_ plotting library to provide this functionality.
One major feature of the Jupyter notebook is the ability to display plots that
are the output of running code cells. The IPython kernel is designed to work
seamlessly with the matplotlib_ plotting library to provide this functionality.
Specific plotting library integration is a feature of the kernel. See the
:ref:`plotting document <ipykernel:plotting>` of the IPython kernel for more
information.
To set this up, before any plotting is performed you must execute the
``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
necessary behind-the-scenes setup for IPython to work correctly hand in hand
with ``matplotlib``; it does *not*, however, actually execute any Python
``import`` commands, that is, no names are added to the namespace.
Installing kernels
------------------
If the ``%matplotlib`` magic is called without an argument, the
output of a plotting command is displayed using the default ``matplotlib``
backend in a separate window. Alternatively, the backend can be explicitly
requested using, for example::
%matplotlib gtk
A particularly interesting backend, provided by IPython, is the ``inline``
backend. This is available only for the IPython Notebook and the
:ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
%matplotlib inline
With this backend, the output of plotting commands is displayed *inline*
within the notebook, directly below the code cell that produced it. The
resulting plots will then also be stored in the notebook document.
.. seealso::
`Plotting with Matplotlib`_ example notebook
Configuring the IPython Notebook
--------------------------------
The notebook server can be run with a variety of command line arguments.
To see a list of available options enter::
$ ipython notebook --help
Defaults for these options can also be set by creating a file named
``ipython_notebook_config.py`` in your IPython *profile folder*. The profile
folder is a subfolder of your IPython directory; to find out where it is
located, run::
$ ipython locate
To create a new set of default configuration files, with lots of information
on available options, use::
$ ipython profile create
.. seealso::
:ref:`config_overview`, in particular :ref:`Profiles`.
:ref:`notebook_server_security`
:ref:`notebook_public_server`
Installing new kernels
----------------------
Running the notebook makes the current python installation available as a kernel. Other
python installations (different python versions, virtualenv or conda environments) can
be installed as kernels by following these steps:
* make sure that the desired python installation is active (e.g. activate the environment)
and ipython is installed
* run once ``ipython kernelspec install-self --user`` (or ``ipython2 ...`` or ``ipython3 ...``
if you want to install specific python versions)
The last command installs a kernel spec file for the current python installation in
``~/.ipython/kernels/``. Kernel spec files are JSON files, which can be viewed and changed with a
normal text editor.
For information on how to install a Python kernel, refer to :ref:`IPython kernel's
installation document <ipykernel:kernel_install>`
Kernels for other languages can be found in the `IPython wiki
<https://github.com/ipython/ipython/wiki/IPython%20kernels%20for%20other%20languages>`_.
@ -458,45 +396,12 @@ you can explicitly trust notebooks, such as those shared with you,
or those that you have written yourself prior to IPython 2.0,
at the command-line with::
$ ipython trust mynotebook.ipynb [other notebooks.ipynb]
$ jupyter trust mynotebook.ipynb [other notebooks.ipynb]
This just generates a new signature stored in each notebook.
You can generate a new notebook signing key with::
$ ipython trust --reset
Importing ``.py`` files
-----------------------
``.py`` files will be imported as a notebook with
the same basename, but an ``.ipynb`` extension, located in the notebook
directory. The notebook created will have just one cell, which will contain
all the code in the ``.py`` file. You can later manually partition this into
individual cells using the ``Edit | Split Cell`` menu option, or the
:kbd:`Ctrl-m -` keyboard shortcut.
Note that ``.py`` scripts obtained from a notebook document using :doc:`nbconvert <nbconvert>`
maintain the structure of the notebook in comments. Reimporting such a
script back into a notebook will preserve this structure.
.. _note_about_roundtrip:
.. warning::
While in simple cases you can "roundtrip" a notebook to Python, edit the
Python file, and then import it back without loss of main content, this is
in general *not guaranteed to work*. First, there is extra metadata
saved in the notebook that may not be saved to the ``.py`` format. And as
the notebook format evolves in complexity, there will be attributes of the
notebook that will not survive a roundtrip through the Python form. You
should think of the Python format as a way to output a script version of a
notebook and the import capabilities as a way to load existing code to get
a notebook started. But the Python version is *not* an alternate notebook
format.
.. seealso::
:ref:`nbformat`
$ jupyter trust --reset
.. include:: links.txt

21
docs/source/public_server.rst
View File

@ -4,9 +4,9 @@ Running a notebook server
=========================
The :ref:`IPython notebook <htmlnotebook>` web-application is based on a
The :ref:`Jupyter notebook <notebook>` web-application is based on a
server-client structure. This server uses a :ref:`two-process kernel
architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
architecture <ipython:ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
and is accessible only from `localhost`. This document describes how you can
:ref:`secure a notebook server <notebook_server_security>` and how to :ref:`run it on
@ -40,7 +40,7 @@ hashed password using the function :func:`IPython.lib.security.passwd`:
argument. **Do not** pass it as an argument inside an IPython session, as it
will be saved in your input history.
You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
You can then add this to your :file:`jupyter_notebook_config.py`, e.g.::
# Password to use for web authentication
c = get_config()
@ -84,13 +84,13 @@ If you want to access your notebook server remotely via a web browser,
you can do the following.
Start by creating a certificate file and a hashed password, as explained
above. Then create a custom profile for the notebook, with the following
command line, type::
above. Then, if you don't already have one, create a config file for the
notebook using the following command line::
$ ipython profile create nbserver
$ jupyter notebook --generate-config
In the profile directory just created, edit the file
``ipython_notebook_config.py``. By default, the file has all fields
In the ``~/.jupyter`` directory, edit the notebook config file,
``jupyter_notebook_config.py``. By default, the file has all fields
commented; the minimum set you need to uncomment and edit is the following::
c = get_config()
@ -104,8 +104,7 @@ commented; the minimum set you need to uncomment and edit is the following::
c.NotebookApp.port = 9999
You can then start the notebook and access it later by pointing your browser
to ``https://your.host.com:9999`` with ``ipython notebook
--profile=nbserver``.
to ``https://your.host.com:9999`` with ``jupyter notebook``.
Firewall Setup
@ -128,7 +127,7 @@ of the notebooks in your working directory) typically lives at the URL
rest of the notebook, under a sub-directory,
e.g. ``http://localhost:8888/ipython/``, you can do so with
configuration options like the following (see above for instructions about
modifying ``ipython_notebook_config.py``)::
modifying ``jupyter_notebook_config.py``)::
c.NotebookApp.base_url = '/ipython/'
c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}

24
docs/source/security.rst
View File

@ -1,9 +1,9 @@
.. _notebook_security:
Security in IPython notebooks
Security in Jupyter notebooks
=============================
As IPython notebooks become more popular for sharing and collaboration,
As Jupyter notebooks become more popular for sharing and collaboration,
the potential for malicious people to attempt to exploit the notebook
for their nefarious purposes increases. IPython 2.0 introduces a
security model to prevent execution of untrusted code without explicit
@ -12,11 +12,11 @@ user input.
The problem
-----------
The whole point of IPython is arbitrary code execution. We have no
The whole point of Jupyter is arbitrary code execution. We have no
desire to limit what can be done with a notebook, which would negatively
impact its utility.
Unlike other programs, an IPython notebook document includes output.
Unlike other programs, an Jupyter notebook document includes output.
Unlike other documents, that output exists in a context that can execute
code (via Javascript).
@ -40,14 +40,14 @@ Our security model
The details of trust
--------------------
IPython notebooks store a signature in metadata, which is used to answer
Jupyter notebooks store a signature in metadata, which is used to answer
the question "Did the current user do this?"
This signature is a digest of the notebooks contents plus a secret key,
known only to the user. The secret key is a user-only readable file in
the IPython profile's security directory. By default, this is::
the Jupyter profile's security directory. By default, this is::
~/.ipython/profile_default/security/notebook_secret
~/.jupyter/profile_default/security/notebook_secret
.. note::
@ -85,7 +85,7 @@ long time. Users can explicitly trust a notebook in two ways:
- At the command-line, with::
ipython trust /path/to/notebook.ipynb
jupyter trust /path/to/notebook.ipynb
- After loading the untrusted notebook, with ``File / Trust Notebook``
@ -95,7 +95,7 @@ the user's key, and then store the newly signed notebook.
Reporting security issues
-------------------------
If you find a security vulnerability in IPython, either a failure of the
If you find a security vulnerability in Jupyter, either a failure of the
code to properly implement the model described here, or a failure of the
model itself, please report it to security@ipython.org.
@ -105,7 +105,7 @@ you can use :download:`this PGP public key <ipython_security.asc>`.
Affected use cases
------------------
Some use cases that work in IPython 1.0 will become less convenient in
Some use cases that work in Jupyter 1.0 will become less convenient in
2.0 as a result of the security changes. We do our best to minimize
these annoyance, but security is always at odds with convenience.
@ -133,9 +133,9 @@ collaborator's key will differ, this will result in each share starting
in an untrusted state. There are three basic approaches to this:
- re-run notebooks when you get them (not always viable)
- explicitly trust notebooks via ``ipython trust`` or the notebook menu
- explicitly trust notebooks via ``jupyter trust`` or the notebook menu
(annoying, but easy)
- share a notebook secret, and use an IPython profile dedicated to the
- share a notebook secret, and use an Jupyter profile dedicated to the
collaboration while working on the project.
Multiple profiles or machines

82
examples/Notebook/Configuring the Notebook and Server.ipynb
View File

@ -11,16 +11,23 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Configuring the IPython Notebook"
"## Configuring the Jupyter Notebook"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The notebook web server can also be configured using IPython profiles and configuration files. The Notebook web server configuration options are set in a file named `ipython_notebook_config.py` in your IPython *profile directory*. The profile directory is a subfolder of your IPython directory, which itself is usually `.ipython` in your home directory.\n",
"The notebook web server can also be configured using Jupyter profiles and configuration files. The Notebook web server configuration options are set in a file named `jupyter_notebook_config.py` in your Jupyter directory, which itself is usually `.jupyter` in your home directory."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The default version of `jupyter_notebook_config.py` lists all of the options available along with documentation for each. Changes made to that file will affect all notebook servers run under that profile. Command line options always override those set in configuration files.\n",
"\n",
"You can display the location of your default profile directory by running the command:"
"You can create a new config:"
]
},
{
@ -31,61 +38,14 @@
},
"outputs": [],
"source": [
"!ipython profile locate default"
"!jupyter notebook --generate-config"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The default version of `ipython_notebook_config.py` lists all of the options available along with documentation for each. Changes made to that file will affect all notebook servers run under that profile. Command line options always override those set in configuration files.\n",
"\n",
"You can create a new profile:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"!ipython profile create my_profile"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And then view its location:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"!ipython profile locate my_profile"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To start the notebook server using a given profile, run the following:\n",
"\n",
" ipython notebook --profile=my_profile"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"More details about IPython configuration files and profiles can be found [here](http://ipython.org/ipython-doc/dev/config/intro.html)."
"More details about Jupyter configuration files and profiles can be found [here](http://ipython.org/ipython-doc/dev/config/intro.html)."
]
},
{
@ -99,7 +59,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The IPython Notebook allows arbitrary code execution on the computer running it. Thus, the notebook web server should never be run on the open internet without first securing it. By default, the notebook server only listens on local network interface (`127.0.0.1`) There are two steps required to secure the notebook server:\n",
"The Jupyter Notebook allows arbitrary code execution on the computer running it. Thus, the notebook web server should never be run on the open internet without first securing it. By default, the notebook server only listens on local network interface (`127.0.0.1`) There are two steps required to secure the notebook server:\n",
"\n",
"1. Setting a password\n",
"2. Encrypt network traffic using SSL"
@ -136,7 +96,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"You can then add this to your `ipython_notebook_config.py`:\n",
"You can then add this to your `jupyter_notebook_config.py`:\n",
"\n",
"```python\n",
"# Password to use for web authentication\n",
@ -171,14 +131,14 @@
"\t\n",
"When you enable SSL support, you will need to access the notebook server over ``https://``, rather than plain ``http://``. The startup message from the notebook server prints the correct URL, but it is easy to overlook and think the server is for some reason non-responsive.\n",
"\n",
"Once you have generated the key and certificate, you can configure the notebook server to use them, by adding the following to `ipython_notebook_config.py`:\n",
"Once you have generated the key and certificate, you can configure the notebook server to use them, by adding the following to `jupyter_notebook_config.py`:\n",
"\n",
"```python\n",
"# The full path to an SSL/TLS certificate file.\n",
"c.NotebookApp.certfile = u'/Users/bgranger/.ipython/profile_my_profile/mycert.crt'\n",
"c.NotebookApp.certfile = u'/Users/bgranger/.jupyter/mycert.crt'\n",
"\n",
"# The full path to a private key file for usage with SSL/TLS.\n",
"c.NotebookApp.keyfile = u'/Users/bgranger/.ipython/profile_my_profile/mycert.key'\n",
"c.NotebookApp.keyfile = u'/Users/bgranger/.jupyter/mycert.key'\n",
"```"
]
},
@ -201,9 +161,9 @@
"\n",
"This can be accomplished by passing a command line options.\n",
"\n",
" ipython notebook --ip=* --no-browser\n",
" jupyter notebook --ip=* --no-browser\n",
"\n",
"You can also add the following to your`ipython_notebook_config.py` file:\n",
"You can also add the following to your `jupyter_notebook_config.py` file:\n",
"\n",
"```python\n",
"c.NotebookApp.ip = '*'\n",
@ -223,7 +183,7 @@
"metadata": {},
"source": [
"The notebook dashboard typically lives at the URL `http://localhost:8888/tree`. If you prefer that it lives, together with the \n",
"rest of the notebook web application, under a base URL prefix, such as `http://localhost:8888/ipython/tree`, you can do so by adding the following lines to your `ipython_notebook_config.py` file.\n",
"rest of the notebook web application, under a base URL prefix, such as `http://localhost:8888/ipython/tree`, you can do so by adding the following lines to your `jupyter_notebook_config.py` file.\n",
"\n",
"```python\n",
"c.NotebookApp.base_url = '/ipython/'\n",
@ -287,7 +247,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

6
examples/Notebook/Connecting with the Qt Console.ipynb
View File

@ -20,12 +20,12 @@
"source": [
"The traditional IPython (`ipython`) consists of a single process that combines a terminal based UI with the process that runs the users code.\n",
"\n",
"While this traditional application still exists, the modern IPython consists of two processes:\n",
"While this traditional application still exists, the modern Jupyter consists of two processes:\n",
"\n",
"* Kernel: this is the process that runs the users code.\n",
"* Frontend: this is the process that provides the user interface where the user types code and sees results.\n",
"\n",
"IPython currently has 3 frontends:\n",
"Jupyter currently has 3 frontends:\n",
"\n",
"* Terminal Console (`ipython console`)\n",
"* Qt Console (`ipython qtconsole`)\n",
@ -124,7 +124,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

317
examples/Notebook/Converting Notebooks With nbconvert.ipynb
View File

@ -1,317 +0,0 @@
{
"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. 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://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 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 template 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 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
}

14
examples/Notebook/Importing Notebooks.ipynb
View File

@ -4,19 +4,19 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Importing IPython Notebooks as Modules"
"# Importing Jupyter Notebooks as Modules"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It is a common problem that people want to import code from IPython Notebooks.\n",
"It is a common problem that people want to import code from Jupyter Notebooks.\n",
"This is made difficult by the fact that Notebooks are not plain Python files,\n",
"and thus cannot be imported by the regular Python machinery.\n",
"\n",
"Fortunately, Python provides some fairly sophisticated [hooks](http://www.python.org/dev/peps/pep-0302/) into the import machinery,\n",
"so we can actually make IPython notebooks importable without much difficulty,\n",
"so we can actually make Jupyter notebooks importable without much difficulty,\n",
"and only using public APIs."
]
},
@ -117,7 +117,7 @@
"outputs": [],
"source": [
"class NotebookLoader(object):\n",
" \"\"\"Module Loader for IPython Notebooks\"\"\"\n",
" \"\"\"Module Loader for Jupyter Notebooks\"\"\"\n",
" def __init__(self, path=None):\n",
" self.shell = InteractiveShell.instance()\n",
" self.path = path\n",
@ -126,7 +126,7 @@
" \"\"\"import a notebook as a module\"\"\"\n",
" path = find_notebook(fullname, self.path)\n",
" \n",
" print (\"importing IPython notebook from %s\" % path)\n",
" print (\"importing Jupyter notebook from %s\" % path)\n",
" \n",
" # load the notebook object\n",
" with io.open(path, 'r', encoding='utf-8') as f:\n",
@ -193,7 +193,7 @@
"outputs": [],
"source": [
"class NotebookFinder(object):\n",
" \"\"\"Module finder that locates IPython Notebooks\"\"\"\n",
" \"\"\"Module finder that locates Jupyter Notebooks\"\"\"\n",
" def __init__(self):\n",
" self.loaders = {}\n",
" \n",
@ -515,7 +515,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

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,

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

@ -99,36 +99,17 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"To inject Javascript we provide an entry point: `custom.js` that allow teh user to execute and load other resources into the notebook.\n",
"To inject Javascript we provide an entry point: `custom.js` that allow the user to execute and load other resources into the notebook.\n",
"Javascript code in `custom.js` will be executed when the notebook app start and can then be used to customise almost anything in the UI and in the behavior of the notebook.\n",
"\n",
"`custom.js` can be found in IPython profile dir, and so you can have different UI modification on a per profile basis, as well as share your modfication with others."
"`custom.js` can be found in the Jupyter dir. You can share your custom.js with others."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### Because we like you...."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"You have been provided with an already existing profile folder with this tutorial...\n",
"start the notebook from the root of the tutorial directory with :\n",
"\n",
"```bash\n",
"$ ipython notebook --ProfileDir.location=./profile_euroscipy\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"##### but back to theory"
"##### Back to theory"
]
},
{
@ -139,8 +120,9 @@
},
"outputs": [],
"source": [
"profile_dir = ! ipython locate\n",
"profile_dir = profile_dir[0]\n",
"import os.path\n",
"profile_dir = '~/.jupyter'\n",
"profile_dir = os.path.expanduser(profile_dir)\n",
"profile_dir"
]
},
@ -160,7 +142,7 @@
"outputs": [],
"source": [
"import os.path\n",
"custom_js_path = os.path.join(profile_dir,'profile_default','static','custom','custom.js')"
"custom_js_path = os.path.join(profile_dir,'custom','custom.js')"
]
},
{
@ -172,9 +154,12 @@
"outputs": [],
"source": [
"# my custom js\n",
"with open(custom_js_path) as f:\n",
" for l in f: \n",
" print l,"
"if os.path.isfile(custom_js_path):\n",
" with open(custom_js_path) as f:\n",
" for l in f: \n",
" print(l)\n",
"else:\n",
" print(\"You don't have a custom.js file\") "
]
},
{
@ -215,7 +200,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Have a look at [default custom.js](https://github.com/ipython/ipython/blob/1.x/IPython/html/static/custom/custom.js), to see it's content and some more explanation."
"Have a look at [default custom.js](https://github.com/ipython/ipython/blob/3.x/IPython/html/static/custom/custom.js), to see it's content and some more explanation."
]
},
{
@ -238,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"
@ -324,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",
@ -358,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",
@ -389,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."
]
},
{
@ -429,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",
@ -479,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'])"
]
},
{
@ -604,7 +589,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.4.3"
"version": "3.4.0"
}
},
"nbformat": 4,

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