Execution Document
==================

nbexec extends Jupyter notebook to display the execution document which displays the notebook description, parameters and command-line examples.

When you create a notebook as ``example.ipynb``, You can see the document by opening ``http://<jupyter_top>/execution_doc/example.ipynb``.

Example:

.. image:: _static/exec_doc_example.png

Notebook Description
--------------------

The first Markdown cell of the notebook is displayed below the heading 'API for notebook ...'.

Parameters Section
------------------

``notebook`` and ``token`` are always required by nbexec. Other parameters are defined parameters in the notebook.

* Parameter: Parameter name which is the key of the parameter definition dict
* Type: Type of the parameter specified as ``type=...``
* Description: Parameter description specified as ``desc='...'``
* Examples: Parameter examples specified as ``examples=[...]``

Usage Examples
--------------

The first value of ``examples=[...]`` is picked and used in the example like ``--data-urlencode "foo=1"``. If the parameter lacks ``examples``, a placeholder is displayed such as ``--data-urlencode "foo=<foo>"``.

Notebook Page
-------------

nbexec also appends the cog button in the Jupyter toolbar which opens the execution document of the current notebook.

.. image:: _static/doc_button.png

(The button is displayed at the end of the toolbar)
