Normal reStructuredText Files¶

This is a normal RST file.

Note

Those still work!

Links to Notebooks (and Other Sphinx Source Files)¶

Links to Sphinx source files can be created like normal Sphinx hyperlinks, just using a relative path to the local file: link.

using a relative path to the local file: link_.

.. _link: subdir/a-notebook-in-a-subdir.ipynb

If the link text has a space (or some other strange character) in it, you have to surround it with backticks: a notebook link.

surround it with backticks: `a notebook link`_.

.. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb

You can also use an anonymous hyperlink target, like this: link. If you have multiple of those, their order matters!

like this: link__.

__ subdir/a-notebook-in-a-subdir.ipynb

Finally, you can use Embedded URIs, like this link.

like this `link <subdir/a-notebook-in-a-subdir.ipynb>`_.

Note

These links should also work on Github and in other rendered reStructuredText pages.

Links to subsections are also possible by adding a hash sign (#) and the section title to any of the above-mentioned link variants. You have to replace spaces in the section titles by hyphens. For example, see this subsection.

For example, see this subsection_.

.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section

Links to Notebooks, Ye Olde Way¶

In addition to the way shown above, you can also create links to notebooks (and other Sphinx source files) with :ref:. This has some disadvantages:

It is arguably a bit more clunky.
Because :ref: is a Sphinx feature, the links don’t work on Github and other rendered reStructuredText pages that use plain old docutils.

It also has one important advantage:

The link text can automatically be taken from the actual section title.

A link with automatic title looks like this: Notebooks in Sub-Directories.

:ref:`/subdir/a-notebook-in-a-subdir.ipynb`

But you can also provide your own link title.

:ref:`your own link title </subdir/a-notebook-in-a-subdir.ipynb>`

However, if you want to use your own title, you are probably better off using the method described above in Links to Notebooks (and Other Sphinx Source Files).

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/a-notebook-in-a-subdir.ipynb#A-Sub-Section`
:ref:`alternative text </subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section>`

Note

The paths have to be relative to the top source directory and they have to start with a slash (/).
Spaces in the section title have to be replaced by hyphens!

Sphinx Directives for Info/Warning Boxes¶

Warning:

This is an experimental feature! Its usage may change in the future or it might disappear completely, so don’t use it for now.

With a bit of luck, it will be possible (some time in the future) to create info/warning boxes in Markdown cells, see https://github.com/jupyter/notebook/issues/1292. If this ever happens, nbsphinx will provide directives for creating such boxes. For now, there are two directives available: nbinfo and nbwarning. This is how an info box looks like:

Note:

This is an info box.

It may include nested formatting, even another info/warning box:

Warning: You should probably not use nested boxes!

Domain Objects¶

example_python_function(foo)¶

This is just for testing domain object links. See this section.

Parameters: foo (str) – Example string parameter

Citations¶

You could use standard Sphinx citations, but it might be more practical to use the sphinxcontrib.bibtex extension.

If you install and enable this extension, you can create citations like [PGH11]:

:cite:`perez2011python`

You can create similar citations in Jupyter notebooks with a special HTML syntax, see the section about citations in Markdown cells.

For those citations to work, you also need to specify a BibTeX file, as explained in the next section.

References¶

After installing and enabling the sphinxcontrib.bibtex extension, you can create a list of references from a BibTeX file like this:

.. bibliography:: references.bib

Have a look at the documentation for all the available options.

The list of references may look something like this:

KRKP+16: Thomas Kluyver, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, Jessica Hamrick, Jason Grout, Sylvain Corlay, Paul Ivanov, Damián Avila, Safia Abdalla, Carol Willing, and Jupyter Development Team. Jupyter Notebooks—a publishing format for reproducible computational workflows. In Fernando Loizides and Birgit Schmidt, editors, Positioning and Power in Academic Publishing: Players, Agents and Agendas, pages 87–90. IOS Press, 2016. doi:10.3233/978-1-61499-649-1-87.
PGH11: Fernando Pérez, Brian E. Granger, and John D. Hunter. Python: an ecosystem for scientific computing. Computing in Science Engineering, 13(2):13–21, 2011. doi:10.1109/MCSE.2010.119.

However, in the LaTeX/PDF output the list of references will not appear here, but at the end of the document. For a possible work-around, see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156.

There is an alternative Sphinx extension for creating bibliographies: https://bitbucket.org/wnielson/sphinx-natbib/. However, this project seems to be abandoned (last commit in 2011).