Merge pull request #124 from jdfreder/docs
Docs
Matthias Bussonnier
11 years ago
commit
9a9a74908b
@ -0,0 +1,44 @@
|
||||
#!/usr/bin/env python
|
||||
|
||||
import os
|
||||
from notebook.notebookapp import NotebookApp
|
||||
|
||||
header = """\
|
||||
.. _config:
|
||||
|
||||
Config
|
||||
======
|
||||
|
||||
The notebook server can be run with a variety of command line arguments.
|
||||
A list of available options can be found below in the :ref:`options section
|
||||
<options>`.
|
||||
|
||||
Defaults for these options can also be set by creating a file named
|
||||
``jupyter_notebook_config.py`` in your Jupyter folder. The Jupyter
|
||||
folder is in your home directory, ``~/.jupyter``.
|
||||
|
||||
To create a ``jupyter_notebook_config.py`` file, with all the defaults
|
||||
commented out, you can use the following command line::
|
||||
|
||||
$ jupyter notebook --generate-config
|
||||
|
||||
|
||||
.. _options:
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
This list of options can be generated by running the following and hitting
|
||||
enter::
|
||||
|
||||
$ jupyter notebook --help
|
||||
|
||||
"""
|
||||
try:
|
||||
destination = os.path.join(os.path.dirname(__file__), 'source/config.rst')
|
||||
except:
|
||||
destination = os.path.join(os.getcwd(), 'config.rst')
|
||||
|
||||
with open(destination, 'w') as f:
|
||||
f.write(header)
|
||||
f.write(NotebookApp().document_config_options())
|
||||
@ -0,0 +1,9 @@
|
||||
jinja2
|
||||
tornado
|
||||
-e git+https://github.com/ipython/ipython_genutils.git#egg=ipython_genutils
|
||||
-e git+https://github.com/ipython/traitlets.git#egg=traitlets
|
||||
-e git+https://github.com/jupyter/jupyter_core.git#egg=jupyter_core
|
||||
-e git+https://github.com/jupyter/nbformat.git#egg=nbformat
|
||||
-e git+https://github.com/jupyter/jupyter_client.git#egg=jupyter_client
|
||||
-e git+https://github.com/ipython/ipython.git#egg=ipython
|
||||
-e git+https://github.com/ipython/ipykernel.git#egg=ipykernel
|
||||
@ -1,168 +0,0 @@
|
||||
.. _nbconvert:
|
||||
|
||||
Converting notebooks to other formats
|
||||
=====================================
|
||||
|
||||
Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which
|
||||
allows you to convert an ``.ipynb`` notebook document file into various static
|
||||
formats.
|
||||
|
||||
Currently, ``nbconvert`` is provided as a command line tool, run as a script
|
||||
using IPython. A direct export capability from within the
|
||||
IPython Notebook web app is planned.
|
||||
|
||||
The command-line syntax to run the ``nbconvert`` script is::
|
||||
|
||||
$ ipython nbconvert --to FORMAT notebook.ipynb
|
||||
|
||||
This will convert the IPython document file ``notebook.ipynb`` into the output
|
||||
format given by the ``FORMAT`` string.
|
||||
|
||||
The default output format is html, for which the ``--to`` argument may be
|
||||
omitted::
|
||||
|
||||
$ ipython nbconvert notebook.ipynb
|
||||
|
||||
IPython provides a few templates for some output formats, and these can be
|
||||
specified via an additional ``--template`` argument.
|
||||
|
||||
The currently supported export formats are:
|
||||
|
||||
* ``--to html``
|
||||
|
||||
- ``--template full`` (default)
|
||||
|
||||
A full static HTML render of the notebook.
|
||||
This looks very similar to the interactive view.
|
||||
|
||||
- ``--template basic``
|
||||
|
||||
Simplified HTML, useful for embedding in webpages, blogs, etc.
|
||||
This excludes HTML headers.
|
||||
|
||||
* ``--to latex``
|
||||
|
||||
Latex export. This generates ``NOTEBOOK_NAME.tex`` file,
|
||||
ready for export.
|
||||
|
||||
- ``--template article`` (default)
|
||||
|
||||
Latex article, derived from Sphinx's howto template.
|
||||
|
||||
- ``--template report``
|
||||
|
||||
Latex report, providing a table of contents and chapters.
|
||||
|
||||
- ``--template basic``
|
||||
|
||||
Very basic latex output - mainly meant as a starting point for custom templates.
|
||||
|
||||
* ``--to pdf``
|
||||
|
||||
Generates a PDF via latex. Supports the same templates as ``--to latex``.
|
||||
|
||||
* ``--to slides``
|
||||
|
||||
This generates a Reveal.js HTML slideshow.
|
||||
It must be served by an HTTP server. The easiest way to do this is adding
|
||||
``--post serve`` on the command-line. The ``serve`` post-processor proxies
|
||||
Reveal.js requests to a CDN if no local Reveal.js library is present.
|
||||
To make slides that don't require an internet connection, just place the
|
||||
Reveal.js library in the same directory where your_talk.slides.html is located,
|
||||
or point to another directory using the ``--reveal-prefix`` alias.
|
||||
|
||||
* ``--to markdown``
|
||||
|
||||
Simple markdown output. Markdown cells are unaffected,
|
||||
and code cells indented 4 spaces.
|
||||
|
||||
* ``--to rst``
|
||||
|
||||
Basic reStructuredText output. Useful as a starting point for embedding notebooks
|
||||
in Sphinx docs.
|
||||
|
||||
* ``--to script``
|
||||
|
||||
Convert a notebook to an executable script.
|
||||
This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
|
||||
If there were any magics in an IPython notebook, this may only be executable from
|
||||
an IPython session.
|
||||
|
||||
* ``--to notebook``
|
||||
|
||||
.. versionadded:: 3.0
|
||||
|
||||
This doesn't convert a notebook to a different format *per se*,
|
||||
instead it allows the running of nbconvert preprocessors on a notebook,
|
||||
and/or conversion to other notebook formats. For example::
|
||||
|
||||
ipython nbconvert --to notebook --execute mynotebook.ipynb
|
||||
|
||||
will open the notebook, execute it, capture new output, and save the result in
|
||||
:file:`mynotebook.nbconvert.ipynb`.
|
||||
|
||||
::
|
||||
|
||||
ipython nbconvert --to notebook --nbformat 3 mynotebook
|
||||
|
||||
will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
|
||||
in version 3 of the :ref:`notebook format <nbformat>`.
|
||||
|
||||
If you want to convert a notebook in-place,
|
||||
you can specify the ouptut file to be the same as the input file::
|
||||
|
||||
ipython nbconvert --to notebook mynb --output mynb
|
||||
|
||||
Be careful with that, since it will replace the input file.
|
||||
|
||||
.. note::
|
||||
|
||||
nbconvert uses pandoc_ to convert between various markup languages,
|
||||
so pandoc is a dependency when converting to latex or reStructuredText.
|
||||
|
||||
.. _pandoc: http://johnmacfarlane.net/pandoc/
|
||||
|
||||
The output file created by ``nbconvert`` will have the same base name as
|
||||
the notebook and will be placed in the current working directory. Any
|
||||
supporting files (graphics, etc) will be placed in a new directory with the
|
||||
same base name as the notebook, suffixed with ``_files``::
|
||||
|
||||
$ ipython nbconvert notebook.ipynb
|
||||
$ ls
|
||||
notebook.ipynb notebook.html notebook_files/
|
||||
|
||||
For simple single-file output, such as html, markdown, etc.,
|
||||
the output may be sent to standard output with::
|
||||
|
||||
$ ipython nbconvert --to markdown notebook.ipynb --stdout
|
||||
|
||||
Multiple notebooks can be specified from the command line::
|
||||
|
||||
$ ipython nbconvert notebook*.ipynb
|
||||
$ ipython nbconvert notebook1.ipynb notebook2.ipynb
|
||||
|
||||
or via a list in a configuration file, say ``mycfg.py``, containing the text::
|
||||
|
||||
c = get_config()
|
||||
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
|
||||
|
||||
and using the command::
|
||||
|
||||
$ ipython nbconvert --config mycfg.py
|
||||
|
||||
|
||||
LaTeX citations
|
||||
---------------
|
||||
|
||||
``nbconvert`` now has support for LaTeX citations. With this capability you
|
||||
can:
|
||||
|
||||
* Manage citations using BibTeX.
|
||||
* Cite those citations in Markdown cells using HTML data attributes.
|
||||
* Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.
|
||||
|
||||
For an example of how this works, please see the citations example in
|
||||
the nbconvert-examples_ repository.
|
||||
|
||||
.. _nbconvert-examples: https://github.com/ipython/nbconvert-examples
|
||||
|
||||
@ -1,358 +0,0 @@
|
||||
.. _nbformat:
|
||||
|
||||
===========================
|
||||
The Jupyter Notebook Format
|
||||
===========================
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
Jupyter (né IPython) notebook files are simple JSON documents,
|
||||
containing text, source code, rich media output, and metadata.
|
||||
each segment of the document is stored in a cell.
|
||||
|
||||
Some general points about the notebook format:
|
||||
|
||||
.. note::
|
||||
|
||||
*All* metadata fields are optional.
|
||||
While the type and values of some metadata are defined,
|
||||
no metadata values are required to be defined.
|
||||
|
||||
|
||||
Top-level structure
|
||||
===================
|
||||
|
||||
At the highest level, a Jupyter notebook is a dictionary with a few keys:
|
||||
|
||||
- metadata (dict)
|
||||
- nbformat (int)
|
||||
- nbformat_minor (int)
|
||||
- cells (list)
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"metadata" : {
|
||||
"signature": "hex-digest", # used for authenticating unsafe outputs on load
|
||||
"kernel_info": {
|
||||
# if kernel_info is defined, its name field is required.
|
||||
"name" : "the name of the kernel"
|
||||
},
|
||||
"language_info": {
|
||||
# if language_info is defined, its name field is required.
|
||||
"name" : "the programming language of the kernel",
|
||||
"version": "the version of the language",
|
||||
"codemirror_mode": "The name of the codemirror mode to use [optional]"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
"nbformat_minor": 0,
|
||||
"cells" : [
|
||||
# list of cell dictionaries, see below
|
||||
],
|
||||
}
|
||||
|
||||
Some fields, such as code input and text output, are characteristically multi-line strings.
|
||||
When these fields are written to disk, they **may** be written as a list of strings,
|
||||
which should be joined with ``''`` when reading back into memory.
|
||||
In programmatic APIs for working with notebooks (Python, Javascript),
|
||||
these are always re-joined into the original multi-line string.
|
||||
If you intend to work with notebook files directly,
|
||||
you must allow multi-line string fields to be either a string or list of strings.
|
||||
|
||||
|
||||
Cell Types
|
||||
==========
|
||||
|
||||
There are a few basic cell types for encapsulating code and text.
|
||||
All cells have the following basic structure:
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"cell_type" : "name",
|
||||
"metadata" : {},
|
||||
"source" : "single string or [list, of, strings]",
|
||||
}
|
||||
|
||||
|
||||
Markdown cells
|
||||
--------------
|
||||
|
||||
Markdown cells are used for body-text, and contain markdown,
|
||||
as defined in `GitHub-flavored markdown`_, and implemented in marked_.
|
||||
|
||||
.. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown
|
||||
.. _marked: https://github.com/chjj/marked
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"cell_type" : "markdown",
|
||||
"metadata" : {},
|
||||
"source" : ["some *markdown*"],
|
||||
}
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
Heading cells have been removed, in favor of simple headings in markdown.
|
||||
|
||||
|
||||
Code cells
|
||||
----------
|
||||
|
||||
Code cells are the primary content of Jupyter notebooks.
|
||||
They contain source code in the language of the document's associated kernel,
|
||||
and a list of outputs associated with executing that code.
|
||||
They also have an execution_count, which must be an integer or ``null``.
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"cell_type" : "code",
|
||||
"execution_count": 1, # integer or null
|
||||
"metadata" : {
|
||||
"collapsed" : True, # whether the output of the cell is collapsed
|
||||
"autoscroll": False, # any of true, false or "auto"
|
||||
},
|
||||
"source" : ["some code"],
|
||||
"outputs": [{
|
||||
# list of output dicts (described below)
|
||||
"output_type": "stream",
|
||||
...
|
||||
}],
|
||||
}
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
``input`` was renamed to ``source``, for consistency among cell types.
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
``prompt_number`` renamed to ``execution_count``
|
||||
|
||||
Code cell outputs
|
||||
-----------------
|
||||
|
||||
A code cell can have a variety of outputs (stream data or rich mime-type output).
|
||||
These correspond to :ref:`messages <messaging>` produced as a result of executing the cell.
|
||||
|
||||
All outputs have an ``output_type`` field,
|
||||
which is a string defining what type of output it is.
|
||||
|
||||
|
||||
stream output
|
||||
*************
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"output_type" : "stream",
|
||||
"name" : "stdout", # or stderr
|
||||
"text" : ["multiline stream text"],
|
||||
}
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
The keys ``stream`` key was changed to ``name`` to match
|
||||
the stream message.
|
||||
|
||||
|
||||
display_data
|
||||
************
|
||||
|
||||
Rich display outputs, as created by ``display_data`` messages,
|
||||
contain data keyed by mime-type. This is often called a mime-bundle,
|
||||
and shows up in various locations in the notebook format and message spec.
|
||||
The metadata of these messages may be keyed by mime-type as well.
|
||||
|
||||
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"output_type" : "display_data",
|
||||
"data" : {
|
||||
"text/plain" : ["multiline text data"],
|
||||
"image/png": ["base64-encoded-png-data"],
|
||||
"application/json": {
|
||||
# JSON data is included as-is
|
||||
"json": "data",
|
||||
},
|
||||
},
|
||||
"metadata" : {
|
||||
"image/png": {
|
||||
"width": 640,
|
||||
"height": 480,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
``application/json`` output is no longer double-serialized into a string.
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
mime-types are used for keys, instead of a combination of short names (``text``)
|
||||
and mime-types, and are stored in a ``data`` key, rather than the top-level.
|
||||
i.e. ``output.data['image/png']`` instead of ``output.png``.
|
||||
|
||||
|
||||
execute_result
|
||||
**************
|
||||
|
||||
Results of executing a cell (as created by ``displayhook`` in Python)
|
||||
are stored in ``execute_result`` outputs.
|
||||
`execute_result` outputs are identical to ``display_data``,
|
||||
adding only a ``execution_count`` field, which must be an integer.
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"output_type" : "execute_result",
|
||||
"execution_count": 42,
|
||||
"data" : {
|
||||
"text/plain" : ["multiline text data"],
|
||||
"image/png": ["base64-encoded-png-data"],
|
||||
"application/json": {
|
||||
# JSON data is included as-is
|
||||
"json": "data",
|
||||
},
|
||||
},
|
||||
"metadata" : {
|
||||
"image/png": {
|
||||
"width": 640,
|
||||
"height": 480,
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
``pyout`` renamed to ``execute_result``
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
``prompt_number`` renamed to ``execution_count``
|
||||
|
||||
|
||||
error
|
||||
*****
|
||||
|
||||
Failed execution may show a traceback
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
'ename' : str, # Exception name, as a string
|
||||
'evalue' : str, # Exception value, as a string
|
||||
|
||||
# The traceback will contain a list of frames,
|
||||
# represented each as a string.
|
||||
'traceback' : list,
|
||||
}
|
||||
|
||||
.. versionchanged:: nbformat 4.0
|
||||
|
||||
``pyerr`` renamed to ``error``
|
||||
|
||||
|
||||
.. _raw nbconvert cells:
|
||||
|
||||
Raw NBConvert cells
|
||||
-------------------
|
||||
|
||||
A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output.
|
||||
For example, this cell could include raw LaTeX for nbconvert to pdf via latex,
|
||||
or restructured text for use in Sphinx documentation.
|
||||
|
||||
The notebook authoring environment does not render raw cells.
|
||||
|
||||
The only logic in a raw cell is the `format` metadata field.
|
||||
If defined, it specifies which nbconvert output format is the intended target
|
||||
for the raw cell. When outputting to any other format,
|
||||
the raw cell's contents will be excluded.
|
||||
In the default case when this value is undefined,
|
||||
a raw cell's contents will be included in any nbconvert output,
|
||||
regardless of format.
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
{
|
||||
"cell_type" : "raw",
|
||||
"metadata" : {
|
||||
# the mime-type of the target nbconvert format.
|
||||
# nbconvert to formats other than this will exclude this cell.
|
||||
"format" : "mime/type"
|
||||
},
|
||||
"source" : ["some nbformat mime-type data"]
|
||||
}
|
||||
|
||||
Backward-compatible changes
|
||||
===========================
|
||||
|
||||
The notebook format is an evolving format. When backward-compatible changes are made,
|
||||
the notebook format minor version is incremented. When backward-incompatible changes are made,
|
||||
the major version is incremented.
|
||||
|
||||
As of nbformat 4.x, backward-compatible changes include:
|
||||
|
||||
- new fields in any dictionary (notebook, cell, output, metadata, etc.)
|
||||
- new cell types
|
||||
- new output types
|
||||
|
||||
New cell or output types will not be rendered in versions that do not recognize them,
|
||||
but they will be preserved.
|
||||
|
||||
Metadata
|
||||
========
|
||||
|
||||
Metadata is a place that you can put arbitrary JSONable information about
|
||||
your notebook, cell, or output. Because it is a shared namespace,
|
||||
any custom metadata should use a sufficiently unique namespace,
|
||||
such as `metadata.kaylees_md.foo = "bar"`.
|
||||
|
||||
Metadata fields officially defined for Jupyter notebooks are listed here:
|
||||
|
||||
Notebook metadata
|
||||
-----------------
|
||||
|
||||
The following metadata keys are defined at the notebook level:
|
||||
|
||||
=========== =============== ==============
|
||||
Key Value Interpretation
|
||||
=========== =============== ==============
|
||||
kernelspec dict A :ref:`kernel specification <kernelspecs>`
|
||||
signature str A hashed :ref:`signature <notebook_security>` of the notebook
|
||||
=========== =============== ==============
|
||||
|
||||
|
||||
Cell metadata
|
||||
-------------
|
||||
|
||||
The following metadata keys are defined at the cell level:
|
||||
|
||||
=========== =============== ==============
|
||||
Key Value Interpretation
|
||||
=========== =============== ==============
|
||||
collapsed bool Whether the cell's output container should be collapsed
|
||||
autoscroll bool or 'auto' Whether the cell's output is scrolled, unscrolled, or autoscrolled
|
||||
deletable bool If False, prevent deletion of the cell
|
||||
format 'mime/type' The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>`
|
||||
name str A name for the cell. Should be unique
|
||||
tags list of str A list of string tags on the cell. Commas are not allowed in a tag
|
||||
=========== =============== ==============
|
||||
|
||||
Output metadata
|
||||
---------------
|
||||
|
||||
The following metadata keys are defined for code cell outputs:
|
||||
|
||||
=========== =============== ==============
|
||||
Key Value Interpretation
|
||||
=========== =============== ==============
|
||||
isolated bool Whether the output should be isolated into an IFrame
|
||||
=========== =============== ==============
|
||||
@ -1,317 +0,0 @@
|
||||
{
|
||||
"cells": [
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"# NbConvert"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Command line usage"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"`NbConvert` is both a library and command line tool that allows you to convert notebooks to other formats. It ships with many common formats: `html`, `latex`, `markdown`, `python`, `rst`, and `slides`\n",
|
||||
"NbConvert relys on the Jinja templating engine, so implementing a new format or tweeking an existing one is easy."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can invoke nbconvert by running\n",
|
||||
"\n",
|
||||
"```bash\n",
|
||||
"$ ipython nbconvert <options and arguments>\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"Call `ipython nbconvert` with the `--help` flag or without any aruments to display the basic help. For detailed configuration help, use the `--help-all` flag."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"### Basic export"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"As a test, the `Index.ipynb` notebook in the directory will be convert. \n",
|
||||
"\n",
|
||||
"If you're converting a notebook with code in it, make sure to run the code cells that you're interested in before attempting to convert the notebook. Unless explicitly requested, nbconvert **does not execute the code cells** of the notebooks that it converts."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%%bash\n",
|
||||
"ipython nbconvert 'Index.ipynb'"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Html is the (configurable) default value. The verbose form of the same command as above is "
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%%bash\n",
|
||||
"ipython nbconvert --to=html 'Index.ipynb'"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can also convert to latex, which will extract the embeded images. If the embeded images are SVGs, inkscape is used to convert them to pdf:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%%bash\n",
|
||||
"ipython nbconvert --to=latex 'Index.ipynb'"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Note that the latex conversion creates latex, not a PDF. To create a PDF you need the required third party packages to compile the latex.\n",
|
||||
"\n",
|
||||
"A `--post` flag is provided for convinience which allows you to have nbconvert automatically compile a PDF for you from your output."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%%bash\n",
|
||||
"ipython nbconvert --to=latex 'Index.ipynb' --post=pdf"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Custom templates"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Look at the first 20 lines of the `python` exporter"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"pyfile = !ipython nbconvert --to python 'Index.ipynb' --stdout\n",
|
||||
"for l in pyfile[20:40]:\n",
|
||||
" print l"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"From the code, you can see that non-code cells are also exported. If you want to change this behavior, you can use a custom template. The custom template inherits from the Python template and overwrites the markdown blocks so that they are empty."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%%writefile simplepython.tpl\n",
|
||||
"{% extends 'python.tpl'%}\n",
|
||||
"\n",
|
||||
"{% block markdowncell -%}\n",
|
||||
"{% endblock markdowncell %}\n",
|
||||
"\n",
|
||||
"## we also want to get rig of header cell\n",
|
||||
"{% block headingcell -%}\n",
|
||||
"{% endblock headingcell %}\n",
|
||||
"\n",
|
||||
"## and let's change the appearance of input prompt\n",
|
||||
"{% block in_prompt %}\n",
|
||||
"# This was input cell with prompt number : {{ cell.prompt_number if cell.prompt_number else ' ' }}\n",
|
||||
"{%- endblock in_prompt %}"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"pyfile = !ipython nbconvert --to python 'Index.ipynb' --stdout --template=simplepython.tpl\n",
|
||||
"\n",
|
||||
"for l in pyfile[4:40]:\n",
|
||||
" print l\n",
|
||||
"print '...'"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"For details about the template syntax, refer to [Jinja's manual](http://jinja2.readthedocs.org/en/latest/intro.html)."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Template that use cells metadata"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The notebook file format supports attaching arbitrary JSON metadata to each cell. Here, as an exercise, you will use the metadata to tags cells."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"First you need to choose another notebook you want to convert to html, and tag some of the cells with metadata. You can refere to the file `soln/celldiff.js` as an example or follow the Javascript tutorial to figure out how do change cell metadata. Assuming you have a notebook with some of the cells tagged as `Easy`|`Medium`|`Hard`|`<None>`, the notebook can be converted specially using a custom template. Design your template in the cells provided below.\n",
|
||||
"\n",
|
||||
"The following, unorganized lines of code, may be of help:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"```\n",
|
||||
"{% extends 'html_full.tpl'%}\n",
|
||||
"{% block any_cell %}\n",
|
||||
"{{ super() }}\n",
|
||||
"<div style=\"background-color:red\">\n",
|
||||
"<div style='background-color:orange'>\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"If your key name under `cell.metadata.example.difficulty`, the following code would get the value of it:\n",
|
||||
"\n",
|
||||
"`cell['metadata'].get('example',{}).get('difficulty','')`\n",
|
||||
"\n",
|
||||
"Tip: Use `%%writefile` to edit the template in the notebook."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%%bash\n",
|
||||
"# ipython nbconvert --to html <your chosen notebook.ipynb> --template=<your template file>"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"%loadpy soln/coloreddiff.tpl"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"# ipython nbconvert --to html '04 - Custom Display Logic.ipynb' --template=soln/coloreddiff.tpl"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"### Get rid of all command line flags."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"IPython nbconvert can be configured using the default profile or a profile specified via the `--profile` flag. Additionally, if a `config.py` file exist in current working directory, nbconvert will use that as config."
|
||||
]
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"kernelspec": {
|
||||
"display_name": "Python 3",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
"language_info": {
|
||||
"codemirror_mode": {
|
||||
"name": "ipython",
|
||||
"version": 3
|
||||
},
|
||||
"file_extension": ".py",
|
||||
"mimetype": "text/x-python",
|
||||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.4.3"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
"nbformat_minor": 0
|
||||
}
|
||||
@ -1,619 +0,0 @@
|
||||
{
|
||||
"cells": [
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"# Using nbconvert as a Library"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"In this Notebook, you will be introduced to the programatic API of nbconvert and how it can be used in various contexts. \n",
|
||||
"\n",
|
||||
"One of [@jakevdp](https://github.com/jakevdp)'s great [blog posts](http://jakevdp.github.io/blog/2013/04/15/code-golf-in-python-sudoku/) will be used to demonstrate. This notebook will not focus on using the command line tool. The attentive reader will point-out that no data is read from or written to disk during the conversion process. Nbconvert has been designed to work in memory so that it works well in a database or web-based environement too."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Quick overview"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Credit, Jonathan Frederic (@jdfreder on github)\n",
|
||||
"\n",
|
||||
"<center>\n",
|
||||
" \n",
|
||||
"</center>"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The main principle of nbconvert is to instantiate an `Exporter` that controls\n",
|
||||
"the pipeline through which notebooks are converted."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"First, download @jakevdp's notebook."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"import requests\n",
|
||||
"response = requests.get('http://jakevdp.github.com/downloads/notebooks/XKCD_plots.ipynb')\n",
|
||||
"response.text[0:60]+'...'"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"If you do not have `requests`, install it by running `pip install requests` (or if you don't have pip installed, you can find it on PYPI)."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The response is a JSON string which represents an IPython notebook. Next, read the response using nbformat.\n",
|
||||
"\n",
|
||||
"Doing this will guarantee that the notebook structure is valid. Note that the in-memory format and on disk format are slightly different. In particual, on disk, multiline strings might be splitted into a list of strings."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from IPython import nbformat\n",
|
||||
"jake_notebook = nbformat.reads(response.text, as_version=4)\n",
|
||||
"jake_notebook.cells[0]"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The nbformat API returns a special dict. You don't need to worry about the details of the structure."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The nbconvert API exposes some basic exporters for common formats and defaults. You will start\n",
|
||||
"by using one of them. First you will import it, then instantiate it using most of the defaults, and finally you will process notebook downloaded early."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from IPython.config import Config\n",
|
||||
"from IPython.nbconvert import HTMLExporter\n",
|
||||
"\n",
|
||||
"# The `basic` template is used here.\n",
|
||||
"# Later you'll learn how to configure the exporter.\n",
|
||||
"html_exporter = HTMLExporter(config=Config({'HTMLExporter':{'default_template':'basic'}}))"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"(body, resources) = html_exporter.from_notebook_node(jake_notebook)"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The exporter returns a tuple containing the body of the converted notebook, raw HTML in this case, as well as a resources dict. The resource dict contains (among many things) the extracted PNG, JPG [...etc] from the notebook when applicable. The basic HTML exporter leaves the figures as embeded base64, but you can configure it to extract the figures. So for now, the resource dict **should** be mostly empty, except for a key containing CSS and a few others whose content will be obvious.\n",
|
||||
"\n",
|
||||
"`Exporter`s are stateless, so you won't be able to extract any usefull information beyond their configuration from them. You can re-use an exporter instance to convert another notebook. Each exporter exposes, for convenience, a `from_file` and `from_filename` method."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"print([key for key in resources ])\n",
|
||||
"print(resources['metadata'])\n",
|
||||
"print(resources['output_extension'])\n",
|
||||
"# print resources['inlining'] # Too long to be shown"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"# Part of the body, here the first Heading\n",
|
||||
"start = body.index('<h1 id', )\n",
|
||||
"print(body[:400]+'...')"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"If you understand HTML, you'll notice that some common tags are ommited, like the `body` tag. Those tags are included in the default `HtmlExporter`, which is what would have been constructed if no Config object was passed into it."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"#### Extracting Figures"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"When exporting you may want to extract the base64 encoded figures as files, this is by default what the `RstExporter` does (as seen below)."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from IPython.nbconvert import RSTExporter\n",
|
||||
"\n",
|
||||
"rst_exporter = RSTExporter()\n",
|
||||
"\n",
|
||||
"(body,resources) = rst_exporter.from_notebook_node(jake_notebook)"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"print(body[:970]+'...')\n",
|
||||
"print('[.....]')\n",
|
||||
"print(body[800:1200]+'...')"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Notice that base64 images are not embeded, but instead there are file name like strings. The strings actually are (configurable) keys that map to the binary data in the resources dict.\n"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Note, if you write an RST Plugin, you are responsible for writing all the files to the disk (or uploading, etc...) in the right location. Of course, the naming scheme is configurable."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"As an exercise, this notebook will show you how to get one of those images."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"list(resources['outputs'])"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"There are 5 extracted binary figures, all `png`s, but they could have been `svg`s which then wouldn't appear in the binary sub dict. Keep in mind that objects with multiple reprs will have every repr stored in the notebook avaliable for conversion. \n",
|
||||
"\n",
|
||||
"Hence if the object provides `_repr_javascript_`, `_repr_latex_`, and `_repr_png_`, you will be able to determine, at conversion time, which representaition is most appropriate. You could even show all of the representaitions of an object in a single export, it's up to you. Doing so would require a little more involvement on your part and a custom Jinja template.\n",
|
||||
"\n",
|
||||
"Back to the task of extracting an image, the Image display object can be used to display one of the images (as seen below)."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from IPython.display import Image\n",
|
||||
"Image(data=resources['outputs']['output_3_0.png'],format='png')"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"This image is being rendered without reading or writing to the disk."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Extracting figures with HTML Exporter ?"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Use case:\n",
|
||||
"\n",
|
||||
"> I write an [awesome blog](http://jakevdp.github.io/) using IPython notebooks converted to HTML, and I want the images to be cached. Having one html file with all of the images base64 encoded inside it is nice when sharing with a coworker, but for a website, not so much. I need an HTML exporter, and I want it to extract the figures!"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"### Some theory"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The process of converting a notebook to a another format with happens in a few steps:\n",
|
||||
"\n",
|
||||
" - Retrieve the notebook and it's accompanying resource (you are responsible for this).\n",
|
||||
" - Feed them into the exporter, which:\n",
|
||||
" - Sequentially feeds them into an array of `Preprocessors`. Preprocessors only act on the **structure** of the notebook, and have unrestricted access to it. \n",
|
||||
" - Feeds the notebook into the Jinja templating engine.\n",
|
||||
" - The template is configured (you can change which one is used).\n",
|
||||
" - Templates make use of configurable macros called `filters`.\n",
|
||||
" - The exporter returns the converted notebook and other relevant resources as a tuple.\n",
|
||||
" - You write the data to the disk, or elsewhere (you are responsible for this too)."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can use `Preprocessors` to accomplish the task at hand. IPython has preprocessors built in which you can use. One of them, the `ExtractOutputPreprocessor` is responsible for crawling the notebook, finding all of the figures, and putting them into the resources directory, as well as choosing the key (i.e. `filename_xx_y.extension`) that can replace the figure inside the template.\n",
|
||||
"\n",
|
||||
"The `ExtractOutputPreprocessor` is special because it's available in all of the `Exporter`s, and is just disabled in some by default."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"# 3rd one should be <ExtractOutputPreprocessor>\n",
|
||||
"html_exporter._preprocessors"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Use the IPython configuration/Traitlets system to enable it. If you have already set IPython configuration options, this system is familiar to you. Configuration options will always of the form:\n",
|
||||
"\n",
|
||||
" ClassName.attribute_name = value\n",
|
||||
" \n",
|
||||
"You can create a configuration object a couple of different ways. Everytime you launch IPython, configuration objects are created from reading config files in your profile directory. Instead of writing a config file, you can also do it programatically using a dictionary. The following creates a config object, that enables the figure extracter, and passes it to an `HTMLExporter`. The output is compared to an `HTMLExporter` without the config object."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from IPython.config import Config\n",
|
||||
"\n",
|
||||
"c = Config({\n",
|
||||
" 'ExtractOutputPreprocessor':{'enabled':True}\n",
|
||||
" })\n",
|
||||
"\n",
|
||||
"exportHTML = HTMLExporter()\n",
|
||||
"exportHTML_and_figs = HTMLExporter(config=c)\n",
|
||||
"\n",
|
||||
"(_, resources) = exportHTML.from_notebook_node(jake_notebook)\n",
|
||||
"(_, resources_with_fig) = exportHTML_and_figs.from_notebook_node(jake_notebook)\n",
|
||||
"\n",
|
||||
"print('resources without the \"figures\" key:')\n",
|
||||
"print(list(resources))\n",
|
||||
"\n",
|
||||
"print('')\n",
|
||||
"print('ditto, notice that there\\'s one more field:')\n",
|
||||
"print(list(resources_with_fig))\n",
|
||||
"list(resources_with_fig['outputs'])"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"#### Custom Preprocessor"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"There are an endless number of transformations that you may want to apply to a notebook. This is why we provide a way to register your own preprocessors that will be applied to the notebook after the default ones.\n",
|
||||
"\n",
|
||||
"To do so, you'll have to pass an ordered list of `Preprocessor`s to the `Exporter`'s constructor. \n",
|
||||
"\n",
|
||||
"For simple cell-by-cell transformations, `Preprocessor` can be created using a decorator. For more complex operations, you need to subclass `Preprocessor` and define a `call` method (as seen below).\n",
|
||||
"\n",
|
||||
"All transforers have a flag that allows you to enable and disable them via a configuration object."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from IPython.nbconvert.preprocessors import Preprocessor\n",
|
||||
"import IPython.config\n",
|
||||
"print(\"Four relevant docstring\")\n",
|
||||
"print('=============================')\n",
|
||||
"print(Preprocessor.__doc__)\n",
|
||||
"print('=============================')\n",
|
||||
"print(Preprocessor.preprocess.__doc__)\n",
|
||||
"print('=============================')\n",
|
||||
"print(Preprocessor.preprocess_cell.__doc__)\n",
|
||||
"print('=============================')"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"### Example"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"The following demonstration was requested in [an IPython GitHub issue](https://github.com/ipython/nbconvert/pull/137#issuecomment-18658235), the ability to exclude a cell by index. \n",
|
||||
"\n",
|
||||
"Inject cells is similar, and won't be covered here. If you want to inject static content at the beginning/end of a notebook, use a custom template."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from traitlets import Integer"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"class PelicanSubCell(Preprocessor):\n",
|
||||
" \"\"\"A Pelican specific preprocessor to remove some of the cells of a notebook\"\"\"\n",
|
||||
" \n",
|
||||
" # I could also read the cells from nbc.metadata.pelican is someone wrote a JS extension\n",
|
||||
" # But I'll stay with configurable value. \n",
|
||||
" start = Integer(0, config=True, help=\"first cell of notebook to be converted\")\n",
|
||||
" end = Integer(-1, config=True, help=\"last cell of notebook to be converted\")\n",
|
||||
" \n",
|
||||
" def preprocess(self, nb, resources):\n",
|
||||
"\n",
|
||||
" #nbc = deepcopy(nb)\n",
|
||||
" nbc = nb\n",
|
||||
" # don't print in real preprocessor !!!\n",
|
||||
" print(\"I'll keep only cells from \", self.start, \"to \", self.end, \"\\n\\n\")\n",
|
||||
" nbc.cells = nb.cells[self.start:self.end] \n",
|
||||
" return nbc, resources"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"# I create this on the fly, but this could be loaded from a DB, and config object support merging...\n",
|
||||
"c = Config()\n",
|
||||
"c.PelicanSubCell.enabled = True\n",
|
||||
"c.PelicanSubCell.start = 4\n",
|
||||
"c.PelicanSubCell.end = 6"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Here a Pelican exporter is created that takes `PelicanSubCell` preprocessors and a `config` object as parameters. This may seem redundant, but with the configuration system you can register an inactive preprocessor on all of the exporters and activate it from config files or the command line. "
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"pelican = RSTExporter(preprocessors=[PelicanSubCell], config=c)"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"print(pelican.from_notebook_node(jake_notebook)[0])"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"### Programatically make templates"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": null,
|
||||
"metadata": {
|
||||
"collapsed": false
|
||||
},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from jinja2 import DictLoader\n",
|
||||
"\n",
|
||||
"dl = DictLoader({'full.tpl': \n",
|
||||
"\"\"\"\n",
|
||||
"{%- extends 'basic.tpl' -%} \n",
|
||||
"\n",
|
||||
"{% block footer %}\n",
|
||||
"FOOOOOOOOTEEEEER\n",
|
||||
"{% endblock footer %}\n",
|
||||
"\"\"\"})\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"exportHTML = HTMLExporter(extra_loaders=[dl])\n",
|
||||
"(body,resources) = exportHTML.from_notebook_node(jake_notebook)\n",
|
||||
"for l in body.split('\\n')[-4:]:\n",
|
||||
" print(l)"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"### Real World Use"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"@jakevdp uses Pelican and IPython Notebook to blog. Pelican [will use](https://github.com/getpelican/pelican-plugins/pull/21) nbconvert programatically to generate blog post. Have a look a [Pythonic Preambulations](http://jakevdp.github.io/) for Jake's blog post."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"@damianavila wrote the Nicholas Plugin to [write blog post as Notebooks](http://www.damian.oquanta.info/posts/one-line-deployment-of-your-site-to-gh-pages.html) and is developping a js-extension to publish notebooks via one click from the web app."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"<center>\n",
|
||||
"<blockquote class=\"twitter-tweet\"><p>As <a href=\"https://twitter.com/Mbussonn\">@Mbussonn</a> requested... easieeeeer! Deploy your Nikola site with just a click in the IPython notebook! <a href=\"http://t.co/860sJunZvj\">http://t.co/860sJunZvj</a> cc <a href=\"https://twitter.com/ralsina\">@ralsina</a></p>— Damián Avila (@damian_avila) <a href=\"https://twitter.com/damian_avila/statuses/370306057828335616\">August 21, 2013</a></blockquote>\n",
|
||||
"</center>"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"##### A few gotchas"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Jinja blocks use `{% %}`by default which does not play nicely with $\\LaTeX$, hence thoses are replaced by `((* *))` in latex templates."
|
||||
]
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"kernelspec": {
|
||||
"display_name": "Python 3",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
"language_info": {
|
||||
"codemirror_mode": {
|
||||
"name": "ipython",
|
||||
"version": 3
|
||||
},
|
||||
"file_extension": ".py",
|
||||
"mimetype": "text/x-python",
|
||||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.4.3"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
"nbformat_minor": 0
|
||||
}
|
||||
|
After Width: | Height: | Size: 4.4 KiB |
Loading…
Reference in new issue