mirror/notebook
2
0
Fork 0
mirror of https://github.com/jupyter/notebook.git synced 2025-01-30 12:11:32 +08:00
Code Issues Packages Projects Releases Wiki Activity

Check in built rst

Browse Source
This commit is contained in:
Jonathan Frederic 2015-06-18 14:08:59 -07:00
parent b41e33ae3a
commit cc551ea657
11 changed files with 2095 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
docs/source/examples/Notebook/Configuring the Notebook and Server.rst Normal file
View File

@ -0,0 +1,188 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Configuring%20the%20Notebook%20and%20Server.ipynb>`__
Configuring the Notebook and Server
===================================
Configuring the Jupyter Notebook
--------------------------------
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.
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.
You can create a new config:
.. code:: python
!jupyter notebook --generate-config
More details about Jupyter configuration files and profiles can be found
`here <http://ipython.org/ipython-doc/dev/config/intro.html>`__.
Securing the notebook server
----------------------------
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:
1. Setting a password
2. Encrypt network traffic using SSL
Setting a password
~~~~~~~~~~~~~~~~~~
You can protect your notebook server with a simple single password by
setting the ``NotebookApp.password`` configurable. You can prepare a
hashed password using the function ``IPython.lib.passwd``:
.. code:: python
from IPython.lib import passwd
password = passwd("secret")
password
You can then add this to your ``jupyter_notebook_config.py``:
.. code:: python
# Password to use for web authentication
c = get_config()
c.NotebookApp.password =
u'sha1:6c2164fc2b22:ed55ecf07fc0f985ab46561483c0e888e8964ae6'
Using SSL/HTTPS
~~~~~~~~~~~~~~~
When using a password, it is a good idea to also use SSL, so that your
password is not sent unencrypted by your browser to the web server. When
running the notebook on the public internet this is absolutely required.
The first step is to generate an SSL certificate. A self-signed
certificate can be generated with ``openssl``. For example, the
following command will create a certificate valid for 365 days with both
the key and certificate data written to the same file:
::
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
In most cases, you should run this command in your profile directory,
which will make it easy to use the generated key and certificate.
When you connect to a notebook server over HTTPS using a self-signed
certificate, your browser will warn you of a dangerous certificate
because it is self-signed. If you want to have a fully compliant
certificate that will not raise warnings, it is possible (but rather
involved) to obtain one, as explained in detail in `this
tutorial <http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars>`__
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.
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``:
.. code:: python
# The full path to an SSL/TLS certificate file.
c.NotebookApp.certfile = u'/Users/bgranger/.jupyter/mycert.crt'
# The full path to a private key file for usage with SSL/TLS.
c.NotebookApp.keyfile = u'/Users/bgranger/.jupyter/mycert.key'
Running a public notebook server
--------------------------------
.. raw:: html
<div class="alert alert-error">
Don't run a public notebook server unless you first secure it with a
password and SSL/HTTPS as described above
.. raw:: html
</div>
By default the notebook server only listens on the
``localhost/127.0.0.1`` network interface. If you want to connect to the
notebook from another computers, or over the internet, you need to
configure the notebook server to listen on all network interfaces and
not open the browser. You will often also want to disable the automatic
launching of the web browser.
This can be accomplished by passing a command line options.
::
jupyter notebook --ip=* --no-browser
You can also add the following to your ``jupyter_notebook_config.py``
file:
.. code:: python
c.NotebookApp.ip = '*'
c.NotebookApp.open_browser = False
Running with a different URL prefix
-----------------------------------
The notebook dashboard typically lives at the URL
``http://localhost:8888/tree``. If you prefer that it lives, together
with the 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.
.. code:: python
c.NotebookApp.base_url = '/ipython/'
c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
Using a different notebook store
--------------------------------
By default, the notebook server stores the notebook documents that it
saves as files in the working directory of the notebook server, also
known as the ``notebook_dir``. This logic is implemented in the
``FileNotebookManager`` class. However, the server can be configured to
use a different notebook manager class, which can store the notebooks in
a different format.
The `bookstore <https://github.com/rgbkrk/bookstore>`__ package
currently allows users to store notebooks on Rackspace CloudFiles or
OpenStack Swift based object stores.
Writing a notebook manager is as simple as extending the base class
``NotebookManager``. The
`simple\_notebook\_manager <https://github.com/khinsen/simple_notebook_manager>`__
provides a great example of an in memory notebook manager, created
solely for the purpose of illustrating the notebook manager API.
Known issues
------------
When behind a proxy, especially if your system or browser is set to
autodetect the proxy, the notebook web application might fail to connect
to the server's websockets, and present you with a warning at startup.
In this case, you need to configure your system not to use the proxy for
the server's address.
For example, in Firefox, go to the Preferences panel, Advanced section,
Network tab, click 'Settings...', and add the address of the notebook
server to the 'No proxy for' field.
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Configuring%20the%20Notebook%20and%20Server.ipynb>`__

67
docs/source/examples/Notebook/Connecting with the Qt Console.rst Normal file
View File

@ -0,0 +1,67 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Connecting%20with%20the%20Qt%20Console.ipynb>`__
Connecting to an existing IPython kernel using the Qt Console
=============================================================
The Frontend/Kernel Model
-------------------------
The traditional IPython (``ipython``) consists of a single process that
combines a terminal based UI with the process that runs the users code.
While this traditional application still exists, the modern Jupyter
consists of two processes:
- Kernel: this is the process that runs the users code.
- Frontend: this is the process that provides the user interface where
the user types code and sees results.
Jupyter currently has 3 frontends:
- Terminal Console (``ipython console``)
- Qt Console (``ipython qtconsole``)
- Notebook (``ipython notebook``)
The Kernel and Frontend communicate over a ZeroMQ/JSON based messaging
protocol, which allows multiple Frontends (even of different types) to
communicate with a single Kernel. This opens the door for all sorts of
interesting things, such as connecting a Console or Qt Console to a
Notebook's Kernel. For example, you may want to connect a Qt console to
your Notebook's Kernel and use it as a help browser, calling ``??`` on
objects in the Qt console (whose pager is more flexible than the one in
the notebook).
This Notebook describes how you would connect another Frontend to a
Kernel that is associated with a Notebook.
Manual connection
-----------------
To connect another Frontend to a Kernel manually, you first need to find
out the connection information for the Kernel using the
``%connect_info`` magic:
.. code:: python
%connect_info
You can see that this magic displays everything you need to connect to
this Notebook's Kernel.
Automatic connection using a new Qt Console
-------------------------------------------
You can also start a new Qt Console connected to your current Kernel by
using the ``%qtconsole`` magic. This will detect the necessary
connection information and start the Qt Console for you automatically.
.. code:: python
a = 10
.. code:: python
%qtconsole
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Connecting%20with%20the%20Qt%20Console.ipynb>`__

71
docs/source/examples/Notebook/Custom Keyboard Shortcuts.rst Normal file
View File

@ -0,0 +1,71 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Custom%20Keyboard%20Shortcuts.ipynb>`__
Keyboard Shortcut Customization
===============================
Starting with IPython 2.0 keyboard shortcuts in command and edit mode
are fully customizable. These customizations are made using the Jupyter
JavaScript API. Here is an example that makes the ``r`` key available
for running a cell:
.. code:: python
%%javascript
Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', {
help : 'run cell',
help_index : 'zz',
handler : function (event) {
IPython.notebook.execute_cell();
return false;
}}
);
"By default the keypress ``r``, while in command mode, changes the type
of the selected cell to ``raw``. This shortcut is overridden by the code
in the previous cell, and thus the action no longer be available via the
keypress ``r``."
There are a couple of points to mention about this API:
- The ``help_index`` field is used to sort the shortcuts in the
Keyboard Shortcuts help dialog. It defaults to ``zz``.
- When a handler returns ``false`` it indicates that the event should
stop propagating and the default action should not be performed. For
further details about the ``event`` object or event handling, see the
jQuery docs.
- If you don't need a ``help`` or ``help_index`` field, you can simply
pass a function as the second argument to ``add_shortcut``.
.. code:: python
%%javascript
Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', function (event) {
IPython.notebook.execute_cell();
return false;
});
Likewise, to remove a shortcut, use ``remove_shortcut``:
.. code:: python
%%javascript
Jupyter.keyboard_manager.command_shortcuts.remove_shortcut('r');
If you want your keyboard shortcuts to be active for all of your
notebooks, put the above API calls into your ``custom.js`` file.
Of course we provide name for majority of existing action so that you do
not have to re-write everything, here is for example how to bind ``r``
back to it's initial behavior:
.. code:: python
%%javascript
Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', 'ipython.change-selected-cell-to-raw-cell');
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Custom%20Keyboard%20Shortcuts.ipynb>`__

36
docs/source/examples/Notebook/Examples and Tutorials Index.rst Normal file
View File

@ -0,0 +1,36 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Examples%20and%20Tutorials%20Index.ipynb>`__
Examples and Tutorials
======================
This portion of the documentation was generated from notebook files. You
can download the original interactive notebook files using the links at
the tops and bottoms of the pages.
Tutorials
---------
- `What is the Jupyter
Notebook <What%20is%20the%20Jupyter%20Notebook.html>`__
- `Notebook Basics <Notebook%20Basics.html>`__
- `Running Code <Running%20Code.html>`__
- `Working With Markdown
Cells <Working%20With%20Markdown%20Cells.html>`__
- `Configuring the Notebook and
Server <Configuring%20the%20Notebook%20and%20Server.html>`__
- `Custom Keyboard Shortcuts <Custom%20Keyboard%20Shortcuts.html>`__
- `JavaScript Notebook
Extensions <JavaScript%20Notebook%20Extensions.html>`__
Examples
--------
- `Importing Notebooks <Importing%20Notebooks.html>`__
- `Connecting with the Qt
Console <Connecting%20with%20the%20Qt%20Console.html>`__
- `Typesetting Equations <Typesetting%20Equations.html>`__
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Examples%20and%20Tutorials%20Index.ipynb>`__

286
docs/source/examples/Notebook/Importing Notebooks.rst Normal file
View File

@ -0,0 +1,286 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Importing%20Notebooks.ipynb>`__
Importing Jupyter Notebooks as Modules
======================================
It is a common problem that people want to import code from Jupyter
Notebooks. This is made difficult by the fact that Notebooks are not
plain Python files, and thus cannot be imported by the regular Python
machinery.
Fortunately, Python provides some fairly sophisticated
`hooks <http://www.python.org/dev/peps/pep-0302/>`__ into the import
machinery, so we can actually make Jupyter notebooks importable without
much difficulty, and only using public APIs.
.. code:: python
import io, os, sys, types
.. code:: python
from IPython import get_ipython
from IPython.nbformat import current
from IPython.core.interactiveshell import InteractiveShell
Import hooks typically take the form of two objects:
1. a Module **Loader**, which takes a module name (e.g.
``'IPython.display'``), and returns a Module
2. a Module **Finder**, which figures out whether a module might exist,
and tells Python what **Loader** to use
.. code:: python
def find_notebook(fullname, path=None):
"""find a notebook, given its fully qualified name and an optional path
This turns "foo.bar" into "foo/bar.ipynb"
and tries turning "Foo_Bar" into "Foo Bar" if Foo_Bar
does not exist.
"""
name = fullname.rsplit('.', 1)[-1]
if not path:
path = ['']
for d in path:
nb_path = os.path.join(d, name + ".ipynb")
if os.path.isfile(nb_path):
return nb_path
# let import Notebook_Name find "Notebook Name.ipynb"
nb_path = nb_path.replace("_", " ")
if os.path.isfile(nb_path):
return nb_path
Notebook Loader
---------------
Here we have our Notebook Loader. It's actually quite simple - once we
figure out the filename of the module, all it does is:
1. load the notebook document into memory
2. create an empty Module
3. execute every cell in the Module namespace
Since IPython cells can have extended syntax, the IPython transform is
applied to turn each of these cells into their pure-Python counterparts
before executing them. If all of your notebook cells are pure-Python,
this step is unnecessary.
.. code:: python
class NotebookLoader(object):
"""Module Loader for Jupyter Notebooks"""
def __init__(self, path=None):
self.shell = InteractiveShell.instance()
self.path = path
def load_module(self, fullname):
"""import a notebook as a module"""
path = find_notebook(fullname, self.path)
print ("importing Jupyter notebook from %s" % path)
# load the notebook object
with io.open(path, 'r', encoding='utf-8') as f:
nb = current.read(f, 'json')
# create the module and add it to sys.modules
# if name in sys.modules:
# return sys.modules[name]
mod = types.ModuleType(fullname)
mod.__file__ = path
mod.__loader__ = self
mod.__dict__['get_ipython'] = get_ipython
sys.modules[fullname] = mod
# extra work to ensure that magics that would affect the user_ns
# actually affect the notebook module's ns
save_user_ns = self.shell.user_ns
self.shell.user_ns = mod.__dict__
try:
for cell in nb.worksheets[0].cells:
if cell.cell_type == 'code' and cell.language == 'python':
# transform the input to executable Python
code = self.shell.input_transformer_manager.transform_cell(cell.input)
# run the code in themodule
exec(code, mod.__dict__)
finally:
self.shell.user_ns = save_user_ns
return mod
The Module Finder
-----------------
The finder is a simple object that tells you whether a name can be
imported, and returns the appropriate loader. All this one does is
check, when you do:
.. code:: python
import mynotebook
it checks whether ``mynotebook.ipynb`` exists. If a notebook is found,
then it returns a NotebookLoader.
Any extra logic is just for resolving paths within packages.
.. code:: python
class NotebookFinder(object):
"""Module finder that locates Jupyter Notebooks"""
def __init__(self):
self.loaders = {}
def find_module(self, fullname, path=None):
nb_path = find_notebook(fullname, path)
if not nb_path:
return
key = path
if path:
# lists aren't hashable
key = os.path.sep.join(path)
if key not in self.loaders:
self.loaders[key] = NotebookLoader(path)
return self.loaders[key]
Register the hook
-----------------
Now we register the ``NotebookFinder`` with ``sys.meta_path``
.. code:: python
sys.meta_path.append(NotebookFinder())
After this point, my notebooks should be importable.
Let's look at what we have in the CWD:
.. code:: python
ls nbpackage
So I should be able to ``import nbimp.mynotebook``.
Aside: displaying notebooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is some simple code to display the contents of a notebook with
syntax highlighting, etc.
.. code:: python
from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter
from IPython.display import display, HTML
formatter = HtmlFormatter()
lexer = PythonLexer()
# publish the CSS for pygments highlighting
display(HTML("""
<style type='text/css'>
%s
</style>
""" % formatter.get_style_defs()
))
.. code:: python
def show_notebook(fname):
"""display a short summary of the cells of a notebook"""
with io.open(fname, 'r', encoding='utf-8') as f:
nb = current.read(f, 'json')
html = []
for cell in nb.worksheets[0].cells:
html.append("<h4>%s cell</h4>" % cell.cell_type)
if cell.cell_type == 'code':
html.append(highlight(cell.input, lexer, formatter))
else:
html.append("<pre>%s</pre>" % cell.source)
display(HTML('\n'.join(html)))
show_notebook(os.path.join("nbpackage", "mynotebook.ipynb"))
So my notebook has a heading cell and some code cells, one of which
contains some IPython syntax.
Let's see what happens when we import it
.. code:: python
from nbpackage import mynotebook
Hooray, it imported! Does it work?
.. code:: python
mynotebook.foo()
Hooray again!
Even the function that contains IPython syntax works:
.. code:: python
mynotebook.has_ip_syntax()
Notebooks in packages
---------------------
We also have a notebook inside the ``nb`` package, so let's make sure
that works as well.
.. code:: python
ls nbpackage/nbs
Note that the ``__init__.py`` is necessary for ``nb`` to be considered a
package, just like usual.
.. code:: python
show_notebook(os.path.join("nbpackage", "nbs", "other.ipynb"))
.. code:: python
from nbpackage.nbs import other
other.bar(5)
So now we have importable notebooks, from both the local directory and
inside packages.
I can even put a notebook inside IPython, to further demonstrate that
this is working properly:
.. code:: python
import shutil
from IPython.utils.path import get_ipython_package_dir
utils = os.path.join(get_ipython_package_dir(), 'utils')
shutil.copy(os.path.join("nbpackage", "mynotebook.ipynb"),
os.path.join(utils, "inside_ipython.ipynb")
)
and import the notebook from ``IPython.utils``
.. code:: python
from IPython.utils import inside_ipython
inside_ipython.whatsmyname()
This approach can even import functions and classes that are defined in
a notebook using the ``%%cython`` magic.
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Importing%20Notebooks.ipynb>`__

389
docs/source/examples/Notebook/JavaScript Notebook Extensions.rst Normal file
View File

@ -0,0 +1,389 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/JavaScript%20Notebook%20Extensions.ipynb>`__
Embrasing web standards
=======================
One of the main reason that allowed us to developp the current notebook
web application was to embrase the web technology.
By beeing a pure web application using HTML, Javascript and CSS, the
Notebook can get all the web technology improvement for free. Thus, as
browsers support for different media extend, The notebook web app should
be able to be compatible without modification.
This is also true with performance of the User Interface as the speed of
javascript VM increase.
The other advantage of using only web technology is that the code of the
interface is fully accessible to the end user, and modifiable live. Even
if this task is not always easy, we strive to keep our code as
accessible and reusable as possible. This should allow with minimum
effort to develop small extensions that customize the behavior of the
web interface.
Tempering with Notebook app
---------------------------
The first tool that is availlable to you and that you shoudl be aware of
are browser "developpers tool". The exact naming can change across
browser, and might require the installation of extensions. But basically
they can allow you to inspect/modify the DOM, and interact with the
javascript code that run the frontend.
- In Chrome and safari Developper tools are in the menu [Put mmenu name
in english here]
- In firefox you might need to install
`Firebug <http://getfirebug.com/>`__
- others ?
Those will be your best friends to debug and try different approach for
your extensions.
Injecting JS
~~~~~~~~~~~~
using magics
^^^^^^^^^^^^
Above tools can be tedious to edit long javascipt files. Hopefully we
provide the ``%%javascript`` magic. This allows you to quickly inject
javascript into the notebook. Still the javascript injected this way
will not survive reloading. Hence it is a good tool for testing an
refinig a script.
You might see here and there people modifying css and injecting js into
notebook by reading file and publishing them into the notebook. Not only
this often break the flow of the notebook and make the re-execution of
the notebook broken, but it also mean that you need to execute those
cells on all the notebook every time you need to update the code.
This can still be usefull in some cases, like the ``%autosave`` magic
that allows to control the time between each save. But this can be
replaced by a Javascript dropdown menu to select save interval.
.. code:: python
## you can inspect the autosave code to see what it does.
%autosave??
custom.js
^^^^^^^^^
To inject Javascript we provide an entry point: ``custom.js`` that allow
the user to execute and load other resources into the notebook.
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.
``custom.js`` can be found in the Jupyter dir. You can share your
custom.js with others.
Back to theory
''''''''''''''
.. code:: python
import os.path
profile_dir = '~/.jupyter'
profile_dir = os.path.expanduser(profile_dir)
profile_dir
and custom js is in
.. code:: python
import os.path
custom_js_path = os.path.join(profile_dir,'custom','custom.js')
.. code:: python
# my custom js
if os.path.isfile(custom_js_path):
with open(custom_js_path) as f:
for l in f:
print(l)
else:
print("You don't have a custom.js file")
Note that ``custom.js`` is ment to be modified by user, when writing a
script, you can define it in a separate file and add a line of
configuration into ``custom.js`` that will fetch and execute the file.
**Warning** : even if modification of ``custom.js`` take effect
immediately after browser refresh (except if browser cache is
aggressive), *creating* a file in ``static/`` directory need a **server
restart**.
Exercise :
----------
- Create a ``custom.js`` in the right location with the following
content:
.. code:: javascript
alert("hello world from custom.js")
- Restart your server and open any notebook.
- Be greeted by custom.js
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.
For the quick ones :
^^^^^^^^^^^^^^^^^^^^
We've seen above that you can change the autosave rate by using a magic.
This is typically something I don't want to type everytime, and that I
don't like to embed into my workwlow and documents. (reader don't care
what my autosave time is), let's build an extension that allow to do it.
Create a dropdow elemement in the toolbar (DOM
``Jupyter.toolbar.element``), you will need
- ``IPython.notebook.set_autosave_interval(miliseconds)``
- know that 1min = 60 sec, and 1 sec = 1000 ms
.. code:: javascript
var label = jQuery('<label/>').text('AutoScroll Limit:');
var select = jQuery('<select/>')
//.append(jQuery('<option/>').attr('value', '2').text('2min (default)'))
.append(jQuery('<option/>').attr('value', undefined).text('disabled'))
// TODO:
//the_toolbar_element.append(label)
//the_toolbar_element.append(select);
select.change(function() {
var val = jQuery(this).val() // val will be the value in [2]
// TODO
// this will be called when dropdown changes
});
var time_m = [1,5,10,15,30];
for (var i=0; i < time_m.length; i++) {
var ts = time_m[i];
//[2] ____ this will be `val` on [1]
// |
// v
select.append($('<option/>').attr('value', ts).text(thr+'min'));
// this will fill up the dropdown `select` with
// 1 min
// 5 min
// 10 min
// 10 min
// ...
}
A non interactive example first
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I like my cython to be nicely highlighted
.. code:: javascript
IPython.config.cell_magic_highlight['magic_text/x-cython'] = {}
IPython.config.cell_magic_highlight['magic_text/x-cython'].reg = [/^%%cython/]
``text/x-cython`` is the name of CodeMirror mode name, ``magic_`` prefix
will just patch the mode so that the first line that contains a magic
does not screw up the highlighting. ``reg``\ is a list or regular
expression that will trigger the change of mode.
Get more docs
^^^^^^^^^^^^^
Sadly you will have to read the js source file (but there are lots of
comments) an/or build the javascript documentation using yuidoc. If you
have ``node`` and ``yui-doc`` installed:
.. code:: bash
$ cd ~/jupyter/notebook/notebook/static/notebook/js/
$ yuidoc . --server
warn: (yuidoc): Failed to extract port, setting to the default :3000
info: (yuidoc): Starting YUIDoc@0.3.45 using YUI@3.9.1 with NodeJS@0.10.15
info: (yuidoc): Scanning for yuidoc.json file.
info: (yuidoc): Starting YUIDoc with the following options:
info: (yuidoc):
{ port: 3000,
nocode: false,
paths: [ '.' ],
server: true,
outdir: './out' }
info: (yuidoc): Scanning for yuidoc.json file.
info: (server): Starting server: http://127.0.0.1:3000
and browse http://127.0.0.1:3000 to get docs
Some convenience methods
^^^^^^^^^^^^^^^^^^^^^^^^
By browsing the doc you will see that we have soem convenience methods
that avoid to re-invent the UI everytime :
.. code:: javascript
Jupyter.toolbar.add_buttons_group([
{
'label' : 'run qtconsole',
'icon' : 'icon-terminal', // select your icon from
// http://fortawesome.github.io/Font-Awesome/icons/
'callback': function(){IPython.notebook.kernel.execute('%qtconsole')}
}
// add more button here if needed.
]);
with a `lot of
icons <http://fortawesome.github.io/Font-Awesome/icons/>`__ you can
select from.
Cell Metadata
-------------
The most requested feature is generaly to be able to distinguish
individual cell in th enotebook, or run specific action with them. 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.
Cell Toolbar
~~~~~~~~~~~~
You can see some example of what can be done by toggling the
``Cell Toolbar`` selector in the toolbar on top of the notebook. It
provide two default ``presets`` that are ``Default`` and ``slideshow``.
Default allow edit the metadata attached to each cell manually.
First we define a function that takes at first parameter an element on
the DOM in which to inject UI element. Second element will be the cell
this element will be registerd with. Then we will need to register that
function ad give it a name.
Register a callback
^^^^^^^^^^^^^^^^^^^
.. code:: python
%%javascript
var CellToolbar = Jupyter.CellToolbar
var toggle = function(div, cell) {
var button_container = $(div)
// let's create a button that show the current value of the metadata
var button = $('<button/>').addClass('btn btn-mini').text(String(cell.metadata.foo));
// On click, change the metadata value and update the button label
button.click(function(){
var v = cell.metadata.foo;
cell.metadata.foo = !v;
button.text(String(!v));
})
// add the button to the DOM div.
button_container.append(button);
}
// now we register the callback under the name foo to give the
// user the ability to use it later
CellToolbar.register_callback('tuto.foo', toggle);
Registering a preset
^^^^^^^^^^^^^^^^^^^^
This function can now be part of many ``preset`` of the CellToolBar.
.. code:: python
%%javascript
Jupyter.CellToolbar.register_preset('Tutorial 1',['tuto.foo','default.rawedit'])
Jupyter.CellToolbar.register_preset('Tutorial 2',['slideshow.select','tuto.foo'])
You should now have access to two presets :
- Tutorial 1
- Tutorial 2
And check that the buttons you defin share state when you toggle preset.
Check moreover that the metadata of the cell is modified when you clisk
the button, and that when saved on reloaded the metadata is still
availlable.
Exercise:
^^^^^^^^^
Try to wrap the all code in a file, put this file in
``{profile}/static/custom/<a-name>.js``, and add
::
require(['custom/<a-name>']);
in ``custom.js`` to have this script automatically loaded in all your
notebooks.
``require`` is provided by a `javascript
library <http://requirejs.org/>`__ that allow to express dependency. For
simple extension like the previous one we directly mute the global
namespace, but for more complexe extension you could pass acallback to
``require([...], <callback>)`` call, to allow the user to pass
configuration information to your plugin.
In Python lang,
.. code:: javascript
require(['a/b', 'c/d'], function( e, f){
e.something()
f.something()
})
could be read as
.. code:: python
import a.b as e
import c.d as f
e.something()
f.something()
See for example @damianavila ["ZenMode"
plugin](https://github.com/ipython-contrib/IPython-notebook-extensions/blob/master/custom.example.js#L34)
:
.. code:: javascript
// read that as
// import custom.zenmode.main as zenmode
require(['custom/zenmode/main'],function(zenmode){
zenmode.background('images/back12.jpg');
})
For the quickest
^^^^^^^^^^^^^^^^
Try to use `the
following <https://github.com/ipython/ipython/blob/1.x/IPython/html/static/notebook/js/celltoolbar.js#L367>`__
to bind a dropdown list to ``cell.metadata.difficulty.select``.
It should be able to take the 4 following values :
- ``<None>``
- ``Easy``
- ``Medium``
- ``Hard``
We will use it to customise the output of the converted notebook
depending of the tag on each cell
.. code:: python
%load soln/celldiff.js
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/JavaScript%20Notebook%20Extensions.ipynb>`__

266
docs/source/examples/Notebook/Notebook Basics.rst Normal file
View File

@ -0,0 +1,266 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Notebook%20Basics.ipynb>`__
Notebook Basics
===============
Running the Notebook Server
---------------------------
The Jupyter notebook server is a custom web server that runs the
notebook web application. Most of the time, users run the notebook
server on their local computer using the command line interface.
Starting the notebook server using the command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can start the notebook server from the command line (Terminal on
Mac/Linux, CMD prompt on Windows) by running the following command:
::
jupyter notebook
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.
When the notebook opens, you will see the **notebook dashboard**, which
will show a list of the notebooks, files, and subdirectories in the
directory where the notebook server was started (as seen in the next
section, below). Most of the time, you will want to start a notebook
server in the highest directory in your filesystem where notebooks can
be found. Often this will be your home directory.
Additional options
~~~~~~~~~~~~~~~~~~
By default, the notebook server starts on port 8888. If port 8888 is
unavailable, the notebook server searchs the next available port.
You can also specify the port manually:
::
jupyter notebook --port 9999
Or start notebook server without opening a web browser.
::
jupyter notebook --no-browser
The notebook server has a number of other command line arguments that
can be displayed with the ``--help`` flag:
::
jupyter notebook --help
The Notebook dashboard
----------------------
When you first start the notebook server, your browser will open to the
notebook dashboard. The dashboard serves as a home page for the
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:
The top of the notebook list displays clickable breadcrumbs of the
current directory. By clicking on these breadcrumbs or on
sub-directories in the notebook list, you can navigate your file system.
To create a new notebook, click on the "New" button at the top of the
list and select a kernel from the dropdown (as seen below). Which
kernels are listed depend on what's installed on the server. Some of the
kernels in the screenshot below may not exist as an option to you.
Notebooks and files can be uploaded to the current directory by dragging
a notebook file onto the notebook list or by the "click here" text above
the list.
The notebook list shows green "Running" text and a green notebook icon
next to running notebooks (as seen below). Notebooks remain running
until you explicitly shut them down; closing the notebook's page is not
sufficient.
To shutdown, delete, duplicate, or rename a notebook check the checkbox
next to it and an array of controls will appear at the top of the
notebook list (as seen below). You can also use the same operations on
directories and files when applicable.
To see all of your running notebooks along with their directories, click
on the "Running" tab:
This view provides a convenient way to track notebooks that you start as
you navigate the file system in a long running notebook server.
Overview of the Notebook UI
---------------------------
If you create a new notebook or open an existing one, you will be taken
to the notebook user interface (UI). This UI allows you to run code and
author notebook documents interactively. The notebook UI has the
following main areas:
- Menu
- Toolbar
- Notebook area and cells
The notebook has an interactive tour of these elements that can be
started in the "Help:User Interface Tour" menu item.
Modal editor
------------
Starting with IPython 2.0, the Jupyter Notebook has a modal user
interface. This means that the keyboard does different things depending
on which mode the Notebook is in. There are two modes: edit mode and
command mode.
Edit mode
~~~~~~~~~
Edit mode is indicated by a green cell border and a prompt showing in
the editor area:
When a cell is in edit mode, you can type into the cell, like a normal
text editor.
.. raw:: html
<div class="alert alert-success">
Enter edit mode by pressing ``Enter`` or using the mouse to click on a
cell's editor area.
.. raw:: html
</div>
Command mode
~~~~~~~~~~~~
Command mode is indicated by a grey cell border:
When you are in command mode, you are able to edit the notebook as a
whole, but not type into individual cells. Most importantly, in command
mode, the keyboard is mapped to a set of shortcuts that let you perform
notebook and cell actions efficiently. For example, if you are in
command mode and you press ``c``, you will copy the current cell - no
modifier is needed.
.. raw:: html
<div class="alert alert-error">
Don't try to type into a cell in command mode; unexpected things will
happen!
.. raw:: html
</div>
.. raw:: html
<div class="alert alert-success">
Enter command mode by pressing ``Esc`` or using the mouse to click
*outside* a cell's editor area.
.. raw:: html
</div>
Mouse navigation
----------------
All navigation and actions in the Notebook are available using the mouse
through the menubar and toolbar, which are both above the main Notebook
area:
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.
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.
The second idea of mouse based navigation is that **cell actions usually
apply to the currently selected cell**. Thus if you want to run the code
in a cell, you would select it and click the
.. raw:: html
<button class='btn btn-default btn-xs'>
.. raw:: html
</button>
button in the toolbar or the "Cell:Run" menu item. Similarly, to copy a
cell you would select it and click the
.. raw:: html
<button class='btn btn-default btn-xs'>
.. raw:: html
</button>
button in the toolbar or the "Edit:Copy" menu item. With this simple
pattern, you should be able to do most everything you need with the
mouse.
Markdown and heading cells have one other state that can be modified
with the mouse. These cells can either be rendered or unrendered. When
they are rendered, you will see a nice formatted representation of the
cell's contents. When they are unrendered, you will see the raw text
source of the cell. To render the selected cell with the mouse, click
the
.. raw:: html
<button class='btn btn-default btn-xs'>
.. raw:: html
</button>
button in the toolbar or the "Cell:Run" menu item. To unrender the
selected cell, double click on the cell.
Keyboard Navigation
-------------------
The modal user interface of the Jupyter Notebook has been optimized for
efficient keyboard usage. This is made possible by having two different
sets of keyboard shortcuts: one set that is active in edit mode and
another in command mode.
The most important keyboard shortcuts are ``Enter``, which enters edit
mode, and ``Esc``, which enters command mode.
In edit mode, most of the keyboard is dedicated to typing into the
cell's editor. Thus, in edit mode there are relatively few shortcuts. In
command mode, the entire keyboard is available for shortcuts, so there
are many more. The ``Help``->``Keyboard Shortcuts`` dialog lists the
available shortcuts.
We recommend learning the command mode shortcuts in the following rough
order:
1. Basic navigation: ``enter``, ``shift-enter``, ``up/k``, ``down/j``
2. Saving the notebook: ``s``
3. Cell types: ``y``, ``m``, ``1-6``, ``t``
4. Cell creation: ``a``, ``b``
5. Cell editing: ``x``, ``c``, ``v``, ``d``, ``z``, ``shift+=``
6. Kernel operations: ``i``, ``.``
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Notebook%20Basics.ipynb>`__

154
docs/source/examples/Notebook/Running Code.rst Normal file
View File

@ -0,0 +1,154 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Running%20Code.ipynb>`__
Running 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.
Code cells allow you to enter and run code
------------------------------------------
Run a code cell using ``Shift-Enter`` or pressing the
.. raw:: html
<button class='btn btn-default btn-xs'>
.. raw:: html
</button>
button in the toolbar above:
.. code:: python
a = 10
.. code:: python
print(a)
There are two other keyboard shortcuts for running code:
- ``Alt-Enter`` runs the current cell and inserts a new one below.
- ``Ctrl-Enter`` run the current cell and enters command mode.
Managing the Kernel
-------------------
Code is run in a separate process called the Kernel. The Kernel can be
interrupted or restarted. Try running the following cell and then hit
the
.. raw:: html
<button class='btn btn-default btn-xs'>
.. raw:: html
</button>
button in the toolbar above.
.. code:: python
import time
time.sleep(10)
If the Kernel dies you will be prompted to restart it. Here we call the
low-level system libc.time routine with the wrong argument via ctypes to
segfault the Python interpreter:
.. code:: python
import sys
from ctypes import CDLL
# This will crash a Linux or Mac system
# equivalent calls can be made on Windows
dll = 'dylib' if sys.platform == 'darwin' else 'so.6'
libc = CDLL("libc.%s" % dll)
libc.time(-1) # BOOM!!
Cell menu
---------
The "Cell" menu has a number of menu items for running code in different
ways. These includes:
- Run and Select Below
- Run and Insert Below
- Run All
- Run All Above
- Run All Below
Restarting the kernels
----------------------
The kernel maintains the state of a notebook's computations. You can
reset this state by restarting the kernel. This is done by clicking on
the
.. raw:: html
<button class='btn btn-default btn-xs'>
.. raw:: html
</button>
in the toolbar above.
sys.stdout and sys.stderr
-------------------------
The stdout and stderr streams are displayed as text in the output area.
.. code:: python
print("hi, stdout")
.. code:: python
from __future__ import print_function
print('hi, stderr', file=sys.stderr)
Output is asynchronous
----------------------
All output is displayed asynchronously as it is generated in the Kernel.
If you execute the next cell, you will see the output one piece at a
time, not all at the end.
.. code:: python
import time, sys
for i in range(8):
print(i)
time.sleep(0.5)
Large outputs
-------------
To better handle large outputs, the output area can be collapsed. Run
the following cell and then single- or double- click on the active area
to the left of the output:
.. code:: python
for i in range(50):
print(i)
Beyond a certain point, output will scroll automatically:
.. code:: python
for i in range(500):
print(2**i - 1)
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Running%20Code.ipynb>`__

238
docs/source/examples/Notebook/Typesetting Equations.rst Normal file
View File

@ -0,0 +1,238 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Typesetting%20Equations.ipynb>`__
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.
Motivating Examples
===================
--------------
The Lorenz Equations
--------------------
Source
~~~~~~
``\begin{align} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{align}``
### Display
.. raw:: latex
\begin{align}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
\end{align}
The Cauchy-Schwarz Inequality
-----------------------------
Source
~~~~~~
``\begin{equation*} \left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right) \end{equation*}``
### Display
.. raw:: latex
\begin{equation*}
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
\end{equation*}
A Cross Product Formula
-----------------------
Source
~~~~~~
``\begin{equation*} \mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix} \mathbf{i} & \mathbf{j} & \mathbf{k} \\ \frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\ \frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \end{vmatrix} \end{equation*}``
### Display
.. raw:: latex
\begin{equation*}
\mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix}
\mathbf{i} & \mathbf{j} & \mathbf{k} \\
\frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\
\frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0
\end{vmatrix}
\end{equation*}
The probability of getting (k) heads when flipping (n) coins is
---------------------------------------------------------------
Source
~~~~~~
``\begin{equation*} P(E) = {n \choose k} p^k (1-p)^{ n-k} \end{equation*}``
### Display
.. raw:: latex
\begin{equation*}
P(E) = {n \choose k} p^k (1-p)^{ n-k}
\end{equation*}
An Identity of Ramanujan
------------------------
Source
~~~~~~
``\begin{equation*} \frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\ldots} } } } \end{equation*}``
### Display
.. raw:: latex
\begin{equation*}
\frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} =
1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}}
{1+\frac{e^{-8\pi}} {1+\ldots} } } }
\end{equation*}
A Rogers-Ramanujan Identity
---------------------------
Source
~~~~~~
``\begin{equation*} 1 + \frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots = \prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})}, \quad\quad \text{for $|q|<1$}. \end{equation*}``
### Display
.. raw:: latex
\begin{equation*}
1 + \frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots =
\prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})},
\quad\quad \text{for $|q|<1$}.
\end{equation*}
Maxwell's Equations
-------------------
Source
~~~~~~
``\begin{align} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} & = 0 \end{align}``
### Display
.. raw:: latex
\begin{align}
\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} & = \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
\nabla \cdot \vec{\mathbf{B}} & = 0
\end{align}
Equation Numbering and References
=================================
--------------
Equation numbering and referencing will be available in a future version
of the Jupyter notebook.
Inline Typesetting (Mixing Markdown and TeX)
============================================
--------------
While display equations look good for a page of samples, the ability to
mix math and *formatted* **text** in a paragraph is also important.
Source
------
``This expression $\sqrt{3x-1}+(1+x)^2$ is an example of a TeX inline equation in a **[Markdown-formatted](http://daringfireball.net/projects/markdown/)** sentence.``
## Display This expression :math:`\sqrt{3x-1}+(1+x)^2` is an example of
a TeX inline equation in a
**`Markdown-formatted <http://daringfireball.net/projects/markdown/>`__**
sentence.
Other Syntax
============
--------------
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.
Source
~~~~~~
::
$$
\begin{array}{c}
y_1 \\\
y_2 \mathtt{t}_i \\\
z_{3,4}
\end{array}
$$
::
$$
\begin{array}{c}
y_1 \cr
y_2 \mathtt{t}_i \cr
y_{3}
\end{array}
$$
::
$$\begin{eqnarray}
x' &=& &x \sin\phi &+& z \cos\phi \\
z' &=& - &x \cos\phi &+& z \sin\phi \\
\end{eqnarray}$$
::
$$
x=4
$$
Display
~~~~~~~
.. math::
\begin{array}{c}
y_1 \\\
y_2 \mathtt{t}_i \\\
z_{3,4}
\end{array}
.. math::
\begin{array}{c}
y_1 \cr
y_2 \mathtt{t}_i \cr
y_{3}
\end{array}
.. math::
\begin{eqnarray}
x' &=& &x \sin\phi &+& z \cos\phi \\
z' &=& - &x \cos\phi &+& z \sin\phi \\
\end{eqnarray}
.. math::
x=4
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Typesetting%20Equations.ipynb>`__

136
docs/source/examples/Notebook/What is the Jupyter Notebook.rst Normal file
View File

@ -0,0 +1,136 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb>`__
What is the Jupyter Notebook?
=============================
Introduction
------------
The Jupyter Notebook is an **interactive computing environment** that
enables users to author notebook documents that include: - Live code -
Interactive widgets - Plots - Narrative text - Equations - Images -
Video
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>`__.
Components
~~~~~~~~~~
The Jupyter Notebook combines three components:
- **The notebook web application**: An interactive web application for
writing and running code interactively and authoring notebook
documents.
- **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.
- **Notebook documents**: Self-contained documents that contain a
representation of all content visible in the notebook web
application, including inputs and outputs of the computations,
narrative text, equations, images, and rich media representations of
objects. Each notebook document has its own kernel.
Notebook web application
------------------------
The notebook web application enables users to:
- **Edit code in the browser**, with automatic syntax highlighting,
indentation, and tab completion/introspection.
- **Run code from the browser**, with the results of computations
attached to the code which generated them.
- See the results of computations with **rich media representations**,
such as HTML, LaTeX, PNG, SVG, PDF, etc.
- Create and use **interactive JavaScript wigets**, which bind
interactive user interface controls and visualizations to reactive
kernel side computations.
- Author **narrative text** using the
`Markdown <https://daringfireball.net/projects/markdown/>`__ markup
language.
- Build **hierarchical documents** that are organized into sections
with different levels of headings.
- Include mathematical equations using **LaTeX syntax in Markdown**,
which are rendered in-browser by
`MathJax <http://www.mathjax.org/>`__.
Kernels
-------
Through Jupyter's kernel and messaging architecture, the Notebook allows
code to be run in a range of different programming languages. For each
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:
- Python(https://github.com/ipython/ipython)
- Julia (https://github.com/JuliaLang/IJulia.jl)
- R (https://github.com/takluyver/IRkernel)
- Ruby (https://github.com/minrk/iruby)
- Haskell (https://github.com/gibiansky/IHaskell)
- Scala (https://github.com/Bridgewater/scala-notebook)
- node.js (https://gist.github.com/Carreau/4279371)
- Go (https://github.com/takluyver/igo)
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.
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."
Notebook documents
------------------
Notebook documents contain the **inputs and outputs** of an interactive
session as well as **narrative text** that accompanies the code but is
not meant for execution. **Rich output** generated by running code,
including HTML, images, video, and plots, is embeddeed in the notebook,
which makes it a complete and self-contained record of a computation.
When you run the notebook web application on your computer, notebook
documents are just **files on your local filesystem with a ``.ipynb``
extension**. This allows you to use familiar workflows for organizing
your notebooks into folders and sharing them with others.
Notebooks consist of a **linear sequence of cells**. There are four
basic cell types:
- **Code cells:** Input and output of live code that is run in the
kernel
- **Markdown cells:** Narrative text with embedded LaTeX equations
- **Heading cells:** 6 levels of hierarchical organization and
formatting
- **Raw cells:** Unformatted text that is included, without
modification, when notebooks are converted to different formats using
nbconvert
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.
**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.
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**.
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb>`__

264
docs/source/examples/Notebook/Working With Markdown Cells.rst Normal file
View File

@ -0,0 +1,264 @@
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Working%20With%20Markdown%20Cells.ipynb>`__
Markdown Cells
==============
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:
http://daringfireball.net/projects/markdown/
Markdown basics
---------------
You can make text *italic* or **bold**.
You can build nested itemized or enumerated lists:
- One
- Sublist
- This
- Sublist - That - The other thing
- Two
- Sublist
- Three
- Sublist
Now another list:
1. Here we go
1. Sublist
2. Sublist
2. There we go
3. Now this
You can add horizontal rules:
--------------
Here is a blockquote:
Beautiful is better than ugly. Explicit is better than implicit.
Simple is better than complex. Complex is better than complicated.
Flat is better than nested. Sparse is better than dense. Readability
counts. Special cases aren't special enough to break the rules.
Although practicality beats purity. Errors should never pass
silently. Unless explicitly silenced. In the face of ambiguity,
refuse the temptation to guess. There should be one-- and preferably
only one --obvious way to do it. Although that way may not be
obvious at first unless you're Dutch. Now is better than never.
Although never is often better than *right* now. If the
implementation is hard to explain, it's a bad idea. If the
implementation is easy to explain, it may be a good idea. Namespaces
are one honking great idea -- let's do more of those!
And shorthand for links:
`Jupyter's website <http://jupyter.org>`__
Headings
--------
If you want, you can add headings using Markdown's syntax:
Heading 1
=========
Heading 2
=========
Heading 2.1
-----------
Heading 2.2
-----------
**BUT most of the time you should use the Notebook's Heading Cells to
organize your Notebook content**, as they provide meaningful structure
that can be interpreted by other tools, not just large bold fonts.
Embedded code
-------------
You can embed code meant for illustration instead of execution in
Python:
::
def f(x):
"""a docstring"""
return x**2
or other languages:
::
if (i=0; i<n; i++) {
printf("hello %d\n", i);
x += 4;
}
LaTeX equations
---------------
Courtesy of MathJax, you can include mathematical expressions both
inline: :math:`e^{i\pi} + 1 = 0` and displayed:
.. math:: e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i
Github flavored markdown (GFM)
------------------------------
The Notebook webapp support Github flavored markdown meaning that you
can use triple backticks for code blocks
.. raw:: html
<pre>
```python
print "Hello World"
```
```javascript
console.log("Hello World")
```
</pre>
Gives
.. code:: python
print "Hello World"
.. code:: javascript
console.log("Hello World")
And a table like this :
.. raw:: html
<pre>
| This | is |
|------|------|
| a | table|
</pre>
A nice Html Table
+--------+---------+
| This | is |
+========+=========+
| a | table |
+--------+---------+
General HTML
------------
Because Markdown is a superset of HTML you can even add things like HTML
tables:
.. raw:: html
<table>
<tr>
<th>
Header 1
.. raw:: html
</th>
<th>
Header 2
.. raw:: html
</th>
</tr>
<tr>
<td>
row 1, cell 1
.. raw:: html
</td>
<td>
row 1, cell 2
.. raw:: html
</td>
</tr>
<tr>
<td>
row 2, cell 1
.. raw:: html
</td>
<td>
row 2, cell 2
.. raw:: html
</td>
</tr>
</table>
Local files
-----------
If you have local files in your Notebook directory, you can refer to
these files in Markdown cells directly:
::
[subdirectory/]<filename>
For example, in the images folder, we have the Python logo:
::
<img src="../images/python_logo.svg" />
and a video with the HTML5 video tag:
::
<video controls src="images/animation.m4v" />
.. raw:: html
<video controls src="images/animation.m4v" />
These do not embed the data into the notebook file, and require that the
files exist when you are viewing the notebook.
Security of local files
~~~~~~~~~~~~~~~~~~~~~~~
Note that this means that the Jupyter notebook server also acts as a
generic file server for files inside the same tree as your notebooks.
Access is not granted outside the notebook folder so you have strict
control over what files are visible, but for this reason it is highly
recommended that you do not run the notebook server with a notebook
directory at a high level in your filesystem (e.g. your home directory).
When you run the notebook in a password-protected manner, local file
access is restricted to authenticated users unless read-only views are
active.
`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Working%20With%20Markdown%20Cells.ipynb>`__