README for NB Builder

Sphinx extension to build NB (IPynb) files.

Requirements

• Sphinx 1.0 or later
• Python 2.6 or later

Installing

Manual

git clone https://github.com/thiersa/nbbuilder
cd nbbuilder
python setup.py install

If you want to take a look and have a try, you can put the IPynb builder in an extension subdirectory, and adjust sys.path to tell Sphinx where to look for it:

• Add the extensions directory to the path in conf.py. E.g.

  sys.path.append(os.path.abspath('exts'))

Usage

• Set the builder as a extension in conf.py:

  extensions = ['sphinxcontrib.nbbuilder']

• Run sphinx-build with target ipynb:

  sphinx-build -b ipynb -c . build/ipynb

Configuration

The following four configuration variables are defined by sphinxcontrib.nbbuilder:

.. confval:: ipynb_file_suffix

   This is the file name suffix for generated Jupyter Notebook files.
   The default is
   ``".ipynb"``.

.. confval:: ipynb_link_suffix

   Suffix for generated links to Jupyter Notebook files.
   The default is whatever
   :confval:`ipynb_file_suffix` is set to.

.. confval:: ipynb_file_transform

   Function to translate a docname to a filename.
   By default, returns `docname` + :confval:`ipynb_file_suffix`.

.. confval:: ipynb_link_transform

   Function to translate a docname to a (partial) URI.
   By default, returns `docname` + :confval:`ipynb_link_suffix`.

Further Reading

Feedback

The IPynb builder is in a preliminary state. It's not (yet) widely used, so any feedback is particularly welcome.