Notebook Heads
==============

``head`` shows the first/last *n* lines of the first/last cell in
Jupyter notebooks.

``head`` is also a good tool to see how you can extend ``nbtoolbelt``
with another tool.
Also see :doc:`extension`.


Options
-------

The following options are supported by ``head``:

.. code-block:: none

  -# NUMBER, --number NUMBER
                        number of head/tail lines to show of first/last cell;
                        < 0 for tail (default: 5)

Number
^^^^^^
By default,
``head`` shows the first 5 lines of the first cell (or fewer, if the cell is shorter).
The ``number`` option determines the desired number of lines,
and whether this is from the head of the first cell (when the number is positive), or
from the tail of the last cell (when the number is negative).
The actual number of lines shown is smaller,
when the cell has fewer lines than desired.


Examples
--------

Show head of notebook ``test.ipynb``:

.. code-block:: bash

  $ nbtb head test.ipynb
  # Test Notebook

  This is a notebook for testing purposes;
  in particular,
  for testing the various scripts.

Show 10 tail lines in last cell of notebook ``test.ipynb``:

.. code-block:: bash

  $ nbtb head -# -10 test.ipynb -v
  Options for nbhead:
    Show last 10 source lines of last cell
  ::::::::::::::
  test.ipynb
  ::::::::::::::
  Last
  cell
  with
  more
  than
  five
  lines.

  Notebooks processed: 1

The last cell apparently contains fewer than 10 lines.