A Normal reStructuredText File ============================== This is a normal RST file. .. note:: Those still work! Links to Notebooks ------------------ Links to notebooks can be easily created: :ref:`subdir/another.ipynb` (the notebook title is used as link text). You can also use :ref:`an alternative text `. The above links were created with: .. code-block:: rst :ref:`subdir/another.ipynb` :ref:`an alternative text ` Links to subsections are also possible, e.g. :ref:`subdir/another.ipynb#A-Sub-Section` (the subsection title is used as link text) and :ref:`alternative text `. These links were created with: .. code-block:: rst :ref:`subdir/another.ipynb#A-Sub-Section` :ref:`alternative text ` .. 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 :ref:`subdir2/included.ipynb`. .. nbinclude:: subdir2/included.ipynb The notebook was included with: .. code-block:: rst .. 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: .. code-block:: ipython3 %file helloworld.py #!/usr/bin/env python3 print('Hello, world!') The ``nbsphinx`` extension provides custom directives to show notebook cells: .. nbinput:: ipython3 :execution-count: 42 6 * 7 .. nboutput:: :execution-count: 42 42 This was created with .. code-block:: rst .. nbinput:: ipython3 :execution-count: 42 6 * 7 .. nboutput:: :execution-count: 42 42