Skip to content

README.rst

Latest commit

 

History

History
86 lines (55 loc) · 1.89 KB

README.rst

File metadata and controls

86 lines (55 loc) · 1.89 KB

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.