A Normal reStructuredText File¶
This is a normal RST file.
Note
Those still work!
Links to Notebooks¶
Links to notebooks can be easily created: A Notebook in a Sub-Directory (the notebook title is used as link text). You can also use an alternative text.
The above links were created with:
:ref:`subdir/another.ipynb`
:ref:`an alternative text <subdir/another.ipynb>`
Links to subsections are also possible, e.g. A Sub-Section (the subsection title is used as link text) and alternative text.
These links were created with:
:ref:`subdir/another.ipynb#A-Sub-Section`
:ref:`alternative text <subdir/another.ipynb#A-Sub-Section>`
Note
- Spaces in the section title have to be replaced by hyphens!
- “
../” is not allowed, you have to specify the full path even if the current source file is in a subdirectory!
Sphinx Directive for Including Notebooks¶
Notebooks can also be included directly in an RST file
using the nbinclude directive.
Below, we include An Included Notebook.
| orphan: |
|---|
An Included Notebook¶
This notebook is included with the nbinclude directive.
The cell below is stored unexecuted, but will be executed when included,
just like notebooks included in a :toctree:. Notebooks with at least
one executed cell will not be executed when included.
In [1]:
6 * 7
Out[1]:
42
The notebook was included with:
.. nbinclude:: subdir2/included.ipynb
Note
- “
../” is allowed here. In fact, you can include notebooks that are outside of the documentation directory!
Sphinx Directives for Jupyter Notebook Cells¶
For comparison, this is a “normal” Sphinx code block using ipython3
syntax highlighting:
%file helloworld.py
#!/usr/bin/env python3
print('Hello, world!')
The nbsphinx extension provides custom directives to show notebook cells:
In [42]:
6 * 7
Out[42]:
42
This was created with
.. nbinput:: ipython3
:execution-count: 42
6 * 7
.. nboutput::
:execution-count: 42
42