.. nbtoolbelt documentation master file, created by
   sphinx-quickstart on Wed Sep  6 17:24:05 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

nbtoolbelt: Tools to Work with Jupyter Notebooks
================================================

Version: |release|


Introduction
------------
When you work with many `Jupyter <https://jupyter.org/>`__
notebooks (e.g., when writing a book or teaching a course),
you will need tools to do bulk operations on notebooks.

``nbtoolbelt`` is an integrated collection of tools to work with Jupyter notebooks.

We use ``nbtoolbelt`` together with
`Momotor <https://momotor.org>`__,
a highly-configurable LTI Tool Provider
that automatically processes digital content
submitted in our Learning Management System
(in our case, students submit Jupyter notebooks),
and returns various forms of feedback.

nbtoolbelt
^^^^^^^^^^
With ``nbtoolbelt`` you get tools and libraries to

* **validate** notebooks (a wrapper for ``nbformat.validate()``)
* inspect **head** or tail cells of notebooks
* **dump** notebooks compactly on the terminal
* summarize notebooks, with statistics (**stats**)
* **view** notebooks in the browser
* **catenate** multiple notebooks into one notebook
* **clean** notebooks
* **run** notebooks, with pre/post cleaning (a wrapper for ``nbconvert.PreProcessor.execute()``)
* **split** notebooks
* **punch** notebooks (shoot holes in them, to produce frameworks useful for exercises)

The next sections briefly discuss some other tools.

nbconvert
^^^^^^^^^
You can use Jupyter's ``nbconvert`` on the command line:

.. code-block:: bash

  jupyter nbconvert --to notebook --execute --allow-errors notebook.ipynb

to **execute** ``notebook.nbconvert.ipynb`` capturing the execution results,
including cells that produce errors.
See the ``nbconvert``  `documentation <https://nbconvert.readthedocs.io/en/latest/index.html>`__
for further details.

nbdime
^^^^^^
You can use ``nbdime`` for selectively **showing**, **diffing**, and **merging** of notebooks.
For instance, when you have installed ``nbdime``, the command

.. code-block:: bash

  nbshow -O nb.ipynb

will show the notebook without outputs of executed code cells.
See the ``nbdime`` `documentation <https://nbdime.readthedocs.io/en/latest/index.html>`__
for further details.


Installation
------------

To install ``nbtoolbelt`` from `PyPI <https://pypi.python.org/>`__ (the Python Package Index):

.. code-block:: bash

  pip install nbtoolbelt

For users who install from a locally saved *wheel*:

.. code-block:: bash

  pip install --no-index --find-links=<path/to/wheel/dir> nbtoolbelt

where ``<path/to/wheel/dir>`` is the (absolute or relative) path
to the directory where you saved the wheel.
The wheel has a name of the form ``nbtoolbelt-*.whl``.

Dependencies
^^^^^^^^^^^^
``nbtoolbelt`` depends on

* ``nbformat`` for notebook structure, and reading and writing of notebooks;
* ``nbconvert`` for notebook validation and execution;
* ``pandas`` and ``numpy`` for summary statistics in the ``stats`` tool.

For testing, it depends on ``pytest`` and ``pytest-mock``.

Upgrading
^^^^^^^^^
To upgrade your ``nbtoolbelt`` installation,
add the ``--upgrade`` flag to the above commands:

.. code-block:: bash

  pip install --upgrade nbtoolbelt

  pip install --upgrade --no-index --find-links=<path/to/wheel/dir> nbtoolbelt

Uninstall
^^^^^^^^^
To uninstall ``nbtoolbelt``:

.. code-block:: bash

  pip uninstall nbtoolbelt

Developers
^^^^^^^^^^
To install for testing:

.. code-block:: bash

   pip install nbtoolbelt[test]


Usage Instructions
------------------

.. toctree::
   :maxdepth: 2
   :caption: nbtoolbelt on Command Line

   nbtoolbelt
   nbvalidate
   nbhead
   nbdump
   nbstats
   nbview
   nbcat
   nbclean
   nbrun
   nbsplit
   nbpunch
   configuration

.. toctree::
   :maxdepth: 2
   :caption: nbtoolbelt as Library

   library
   apidoc


.. toctree::
   :maxdepth: 2
   :caption: nbtoolbelt Development

   extension
   testing


.. toctree::
   :maxdepth: 2
   :caption: nbtoolbelt Change Log

   CHANGELOG


References
----------

* The structure of Jupyter notebooks is specified in ``nbformat``
  (`documentation <https://nbformat.readthedocs.io/en/latest/index.html>`__).
  The library ``nbformat`` facilitates programmatic manipulation of notebooks.

* Tool to convert notebooks: ``nbconvert``
  (`documentation <https://nbconvert.readthedocs.io/en/latest/index.html>`__);
  can be used on the command line and as a library for conversion to various other formats,
  including notebook execution and other notebook versions.
  It also provides a set of notebook preprocessors.

* Tools for showing, diffing, and merging Jupyter notebooks,
  including Git integration: ``nbdime``
  (`documentation <https://nbdime.readthedocs.io/en/latest/index.html>`__)


License and Source Code
-----------------------

This software is made available under the terms of the :download:`MIT License <LICENSE.txt>`.

Copyright (c) 2017-2020 - Eindhoven University of Technology, The Netherlands

The source code and issue tracker are at <https://gitlab.tue.nl/jupyter-projects/nbtoolbelt/>.

.. toctree::
   :maxdepth: 2

   source_code


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`

..
 * :ref:`search`