nbinteract
CLI toolInstalling 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')