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

Merge pull request #3831 from minrk/nbdoc

Browse Source 
update nbconvert doc with new CLI
This commit is contained in:
Min RK 2013-07-30 14:56:02 -07:00
commit 50fba9453e
3 changed files with 214 additions and 282 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
docs/source/interactive/converting_notebooks.rst
View File

@ -1,261 +0,0 @@
.. _`nbconvert script`:
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. In the future, 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 --format=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 ``--format`` modifier may be
omitted::
$ ipython nbconvert notebook.ipynb
The currently supported export formats are the following:
* HTML:
- **full_html**:
Standard HTML
- **simple_html**:
Simplified HTML
- **reveal**:
HTML slideshow presentation for use with the ``reveal.js`` package
* PDF:
- **sphinx_howto**:
The format for Sphinx_ HOWTOs; similar to an ``article`` in LaTeX
- **sphinx_manual**:
The format for Sphinx_ manuals; similar to a ``book`` in LaTeX
- **latex**:
An article formatted completely using LaTeX
* Markup:
- **rst**:
reStructuredText_ markup
- **markdown**:
Markdown_ markup
.. _Sphinx: http://sphinx-doc.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Markdown: http://daringfireball.net/projects/markdown/syntax
* Python:
Comments out all the non-Python code to produce a ``.py`` Python
script with just the code content. Currently the output includes IPython
magics, and so can be run with ``ipython``, after changing the extension
of the script to ``.ipy``.
The files 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/
Each of the options for PDF export produces as an intermediate step a LaTeX
``.tex`` file with the same basename as the notebook, as well as individual
files for each figure, and ``.text`` files with textual output from running
code cells.
To actually produce the final PDF file, run the following commands::
$ ipython nbconvert --format=latex notebook.ipynb
$ pdflatex notebook
This requires a local installation of LaTeX on your machine.
The output is a PDF file ``notebook.pdf``, also placed inside the
``nbconvert_build`` subdirectory.
Alternatively, the output may be sent to standard output with::
$ ipython nbconvert 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
Extracting standard Python files from notebooks
-----------------------------------------------
``.ipynb`` notebook document files are plain text files which store a
representation in JSON format of the contents of a notebook space. As such,
they are not valid ``.py`` Python scripts, and so can be neither imported
directly with ``import`` in Python, nor run directly as a standard Python
script (though both of these are possible with simple workarounds).
To extract the Python code from within a notebook document, the simplest
method is to use the ``File | Download as | Python (.py)`` menu item; the
resulting ``.py`` script will be downloaded to your browser's default
download location.
An alternative is to pass an argument to the IPython Notebook, from the moment
when it is originally started, specifying that whenever it saves an ``.ipynb``
notebook document, it should, at the same time, save the corresponding
``.py`` script. To do so, you can execute the following command::
$ ipython notebook --script
or you can set this option permanently in your configuration file with::
c = get_config()
c.NotebookManager.save_script=True
The result is that standard ``.py`` files are also now generated, which
can be ``%run``, imported from regular IPython sessions or other notebooks, or
executed at the command line, as usual. Since the raw code you have typed is
exported, you must avoid using syntax such as IPython magics and other
IPython-specific extensions to the language for the files to be able to be
successfully imported.
.. or you can change the script's extension to ``.ipy`` and run it with::
..
.. $ ipython script.ipy
In normal Python practice, the standard way to differentiate importable code
in a Python script from the "executable" part of a script is to use the
following idiom at the start of the executable part of the code::
if __name__ == '__main__'
# rest of the code...
Since all cells in the notebook are run as top-level code, you will need to
similarly protect *all* cells that you do not want executed when other scripts
try to import your notebook. A convenient shortand for this is to define
early on::
script = __name__ == '__main__'
Then in any cell that you need to protect, use::
if script:
# rest of the cell...
.. _notebook_format:
Notebook JSON file format
-------------------------
Notebook documents are JSON files with an ``.ipynb`` extension, formatted
as legibly as possible with minimal extra indentation and cell content broken
across lines to make them reasonably friendly to use in version-control
workflows. You should be very careful if you ever manually edit this JSON
data, as it is extremely easy to corrupt its internal structure and make the
file impossible to load. In general, you should consider the notebook as a
file meant only to be edited by the IPython Notebook app itself, not for
hand-editing.
.. note::
Binary data such as figures are also saved directly in the JSON file.
This provides convenient single-file portability, but means that the
files can be large; a ``diff`` of binary data is also not very
meaningful. Since the binary blobs are encoded in a single line, they
affect only one line of the ``diff`` output, but they are typically very
long lines. You can use the ``Cell | All Output | Clear`` menu option to
remove all output from a notebook prior to committing it to version
control, if this is a concern.
The notebook server can also generate a pure Python version of your notebook,
using the ``File | Download as`` menu option. The resulting ``.py`` file will
contain all the code cells from your notebook verbatim, and all Markdown cells
prepended with a comment marker. The separation between code and Markdown
cells is indicated with special comments and there is a header indicating the
format version. All output is removed when exporting to Python.
As an example, consider a simple notebook called ``simple.ipynb`` which
contains one Markdown cell, with the content ``The simplest notebook.``, one
code input cell with the content ``print "Hello, IPython!"``, and the
corresponding output.
The contents of the notebook document ``simple.ipynb`` is the following JSON
container::
{
"metadata": {
"name": "simple"
},
"nbformat": 3,
"nbformat_minor": 0,
"worksheets": [
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": "The simplest notebook."
},
{
"cell_type": "code",
"collapsed": false,
"input": "print \"Hello, IPython\"",
"language": "python",
"metadata": {},
"outputs": [
{
"output_type": "stream",
"stream": "stdout",
"text": "Hello, IPython\n"
}
],
"prompt_number": 1
}
],
"metadata": {}
}
]
}
The corresponding Python script is::
# -*- coding: utf-8 -*-
# <nbformat>3.0</nbformat>
# <markdowncell>
# The simplest notebook.
# <codecell>
print "Hello, IPython"
Note that indeed the output of the code cell, which is present in the JSON
container, has been removed in the ``.py`` script.

212
docs/source/interactive/nbconvert.rst Normal file
View File

@ -0,0 +1,212 @@
.. _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. You can automatically run latex on it to generate a PDF
by adding ``--post PDF``.
- ``--template article`` (default)
Latex article, derived from Sphinx's howto template.
- ``--template book``
Latex book, derived from Sphinx's manual template.
- ``--template basic``
Very basic latex output - mainly meant as a starting point for custom templates.
* ``--to slides``
This generates a Reveal.js HTML slideshow.
It must be served by an HTTP server. The easiest way to get this is to add
``--post serve`` on the command-line.
* ``--to markdown``
Simple markdown output. Markdown cells are unaffected,
and code cells are placed in triple-backtick (``\`\`\```) blocks.
* ``--to rst``
Basic reStructuredText output. Useful as a starting point for embedding notebooks
in Sphinx docs.
* ``--to python``
Convert a notebook to an executable Python script.
This is the simplest way to get a Python script out of a notebook.
If there were any magics in the notebook, this may only be executable from
an IPython session.
.. note::
nbconvert uses pandoc_ to convert between various markup languages,
so pandoc is a dependency of most nbconvert transforms,
excluding Markdown and Python.
.. _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
.. _notebook_format:
Notebook JSON file format
-------------------------
Notebook documents are JSON files with an ``.ipynb`` extension, formatted
as legibly as possible with minimal extra indentation and cell content broken
across lines to make them reasonably friendly to use in version-control
workflows. You should be very careful if you ever manually edit this JSON
data, as it is extremely easy to corrupt its internal structure and make the
file impossible to load. In general, you should consider the notebook as a
file meant only to be edited by the IPython Notebook app itself, not for
hand-editing.
.. note::
Binary data such as figures are also saved directly in the JSON file.
This provides convenient single-file portability, but means that the
files can be large; a ``diff`` of binary data is also not very
meaningful. Since the binary blobs are encoded in a single line, they
affect only one line of the ``diff`` output, but they are typically very
long lines. You can use the ``Cell | All Output | Clear`` menu option to
remove all output from a notebook prior to committing it to version
control, if this is a concern.
The notebook server can also generate a pure Python version of your notebook,
using the ``File | Download as`` menu option. The resulting ``.py`` file will
contain all the code cells from your notebook verbatim, and all Markdown cells
prepended with a comment marker. The separation between code and Markdown
cells is indicated with special comments and there is a header indicating the
format version. All output is removed when exporting to Python.
As an example, consider a simple notebook called ``simple.ipynb`` which
contains one Markdown cell, with the content ``The simplest notebook.``, one
code input cell with the content ``print "Hello, IPython!"``, and the
corresponding output.
The contents of the notebook document ``simple.ipynb`` is the following JSON
container::
{
"metadata": {
"name": "simple"
},
"nbformat": 3,
"nbformat_minor": 0,
"worksheets": [
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": "The simplest notebook."
},
{
"cell_type": "code",
"collapsed": false,
"input": "print \"Hello, IPython\"",
"language": "python",
"metadata": {},
"outputs": [
{
"output_type": "stream",
"stream": "stdout",
"text": "Hello, IPython\n"
}
],
"prompt_number": 1
}
],
"metadata": {}
}
]
}
The corresponding Python script is::
# -*- coding: utf-8 -*-
# <nbformat>3.0</nbformat>
# <markdowncell>
# The simplest notebook.
# <codecell>
print "Hello, IPython"
Note that indeed the output of the code cell, which is present in the JSON
container, has been removed in the ``.py`` script.

23
docs/source/interactive/notebook.rst
View File

@ -477,26 +477,7 @@ setup for IPython to work correctly hand in hand with ``matplotlib``; it does
*not*, however, actually execute any Python ``import`` commands, that is, no *not*, however, actually execute any Python ``import`` commands, that is, no
names are added to the namespace. names are added to the namespace.
For more agile *interactive* use of the notebook space, an alternative magic, If the ``%matplotlib`` magic is called without an argument, the
``%pylab``, is provided. This does the same work as the ``%matplotlib`` magic,
but *in addition* it automatically executes a standard sequence of ``import``
statements required to work with the ``%matplotlib`` library, importing the
following names into the namespace:
``numpy`` as ``np``; ``matplotlib.pyplot`` as ``plt``;
``matplotlib``, ``pylab`` and ``mlab`` from ``matplotlib``; and *all names*
from within ``numpy`` and ``pylab``.
However, the use of ``%pylab`` is discouraged, since names coming from
different packages may collide. In general, the use of ``from package import
*`` is discouraged. A better option is then::
%pylab --no-import-all
which imports the names listed above, but does *not* perform this
``import *`` imports.
If the ``%matplotlib`` or ``%pylab` magics are called without an argument, the
output of a plotting command is displayed using the default ``matplotlib`` output of a plotting command is displayed using the default ``matplotlib``
backend in a separate window. Alternatively, the backend can be explicitly backend in a separate window. Alternatively, the backend can be explicitly
requested using, for example:: requested using, for example::
@ -504,7 +485,7 @@ requested using, for example::
%matplotlib gtk %matplotlib gtk
A particularly interesting backend is the ``inline`` backend. A particularly interesting backend is the ``inline`` backend.
This is applicable only for the IPython Notebook and the IPython Qtconsole. This is applicable only for the IPython Notebook and the IPython QtConsole.
It can be invoked as follows:: It can be invoked as follows::
%matplotlib inline %matplotlib inline