nbsphinx-link¶

Version: 1.1.0

nbsphinx-link is a sphinx extension built on nbsphinx that allows you to include Jupyter notebooks that sit outside your sphinx source directory in your documentation.

In this documentation, the Installation section is written as a notebook included with nbsphinx, while the Introduction section is written as a notebook included with nbsphinx-link.

Contents¶

This page was generated from docs/source/installing.ipynb.

Installation¶

To install nbsphinx-link, run the following from a shell:

pip install nbsphinx-link

and add both nbsphinx and nbsphinx_link as extensions in your Sphinx build config, typicalyl in conf.py:

extensions = [
    # ...
    # any other extensions you need,
    # ...
    'nbsphinx',
    'nbsphinx_link',
]

This page was generated from notebooks/introduction.ipynb.

Introduction¶

For a start, consider the documentation folder of the nbsphinx-link repository. This documentation page itself comes from a linked notebook:

In [1]:

def foo(a):
    return 'foo' + a

print(foo('bar'))

foobar

After the installation steps (installing the package, and adding nbsphinx_link as an extension in the Sphinx config), you can link external notebooks by including .nblink files in your documentation source tree. The format of the link file is as follows:

{
    "path": "relative/path/to/notebook"
}

It should then Just Work. For further information and examples, consider inspecting the Sphinx config file of the nbsphinx-link repository!