mirror of
https://github.com/jupyter/notebook.git
synced 2025-01-30 12:11:32 +08:00
Merge pull request #3831 from minrk/nbdoc
update nbconvert doc with new CLI
This commit is contained in:
Min RK
commit
50fba9453e
@ -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
212
docs/source/interactive/nbconvert.rst
Normal 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.
|
||||
|
||||
@ -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
|
||||
names are added to the namespace.
|
||||
|
||||
For more agile *interactive* use of the notebook space, an alternative magic,
|
||||
``%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
|
||||
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::
|
||||
@ -504,7 +485,7 @@ requested using, for example::
|
||||
%matplotlib gtk
|
||||
|
||||
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::
|
||||
|
||||
%matplotlib inline
|
||||
|
||||
Loading…
Reference in New Issue
Block a user