Exporting With nbinteract

nbinteract comes with two options for exporting Jupyter notebooks into standalone HTML pages: using the nbinteract command line tool and running nbi.publish() in a notebook cell.

The nbinteract CLI tool

Installing the nbinteract package installs a command-line tool for converting notebooks into HTML pages.

For example, to convert a notebook called Hello.ipynb using the Binder spec calebs11/nbinteract-image/master:

# `master` is optional since it is the default
nbinteract Hello.ipynb -s calebs11/nbinteract-image

After running nbinteract init, you may omit the -s flag and simply write:

nbinteract Hello.ipynb

One advantage of the command line tool is that it can convert notebooks in folders as well as individual notebooks:

# Using the -r flag tells nbinteract to recursively search for .ipynb files
# in nb_folder
nbinteract -r nb_folder/

For the complete set of options, run nbinteract --help.

$ nbinteract --help
`nbinteract NOTEBOOKS ...` converts notebooks into HTML pages. Note that
running this command outside a GitHub project initialized with `nbinteract
init` requires you to specify the --spec SPEC option.

Arguments:
  NOTEBOOKS  List of notebooks or folders to convert. If folders are passed in,
             all the notebooks in each folder are converted. The resulting HTML
             files are created adjacent to their originating notebooks and will
             clobber existing files of the same name.

             By default, notebooks in subfolders will not be converted; use the
             --recursive flag to recursively convert notebooks in subfolders.

Options:
  -h --help                  Show this screen
  -s SPEC --spec SPEC        BinderHub spec for Jupyter image. Must be in the
                             format: `{username}/{repo}/{branch}`. For example:
                             'SamLau95/nbinteract-image/master'. This flag is
                             **required** unless a .nbinteract.json file exists
                             in the project root with the "spec" key. If branch
                             is not specified, default to `master`.
  -t TYPE --template TYPE    Specifies the type of HTML page to generate. Valid
                             types: full (standalone page), partial (embeddable
                             page with library), or plain (embeddable page
                             without JS).
                             [default: full]
  -B --no-top-button         If set, doesn't generate button at top of page.
  -r --recursive             Recursively convert notebooks in subdirectories.
  -o FOLDER --output=FOLDER  Outputs HTML files into FOLDER instead of
                             outputting files adjacent to their originating
                             notebooks. All files will be direct descendants of
                             the folder even if --recursive is set.
  -i FOLDER --images=FOLDER  Extracts images from HTML and writes into FOLDER
                             instead of encoding images in base64 in the HTML.
                             Requires -o option to be set as well.
  -e --execute               Executes the notebook before converting to HTML,
                             functioning like the equivalent flag for
                             nbconvert. Configure NbiExecutePreprocessor to
                             change conversion instead of the base
                             ExecutePreprocessor.

nbi.publish()

The nbi.publish() method can be run inside a Jupyter notebook cell. It has the following signature:

import nbinteract as nbi

nbi.publish(spec, nb_name, template='full', save_first=True)
'''
Converts nb_name to an HTML file. Preserves widget functionality.

Outputs a link to download HTML file after conversion if called in a
notebook environment.

Equivalent to running `nbinteract ${spec} ${nb_name}` on the command line.

Args:
    spec (str): BinderHub spec for Jupyter image. Must be in the format:
        `${username}/${repo}/${branch}`.

    nb_name (str): Complete name of the notebook file to convert. Can be a
        relative path (eg. './foo/test.ipynb').

    template (str): Template to use for conversion. Valid templates:

        - 'full': Outputs a complete standalone HTML page with default
          styling. Automatically loads the nbinteract JS library.
        - 'partial': Outputs an HTML partial that can be embedded in
          another page. Automatically loads the nbinteract JS library.
        - 'gitbook': Outputs an HTML partial used to embed in a Gitbook or
          other environments where the nbinteract JS library is already
          loaded.

    save_first (bool): If True, saves the currently opened notebook before
        converting nb_name. Used to ensure notebook is written to
        filesystem before starting conversion. Does nothing if not in a
        notebook environment.


Returns:
    None
'''

For example, to convert a notebook called Hello.ipynb using the Binder spec calebs11/nbinteract-image/master:

nbi.publish('calebs11/nbinteract-image/master', 'Hello.ipynb')