Normal reStructuredText Files#

This is a normal RST file.


Those still work!

Sphinx Directives for Info/Warning Boxes#


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 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:


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#


This is just for testing domain object links.


foo (str) – Example string parameter


There are different ways of handling references, for example you could use the standard Sphinx citations, but it might be more practical to use the sphinxcontrib.bibtex extension.

After installing the sphinxcontrib.bibtex extension, you have to enable it in your and select the BibTeX file(s) you want to use:

extensions = [
    # Probably more extensions here ...

bibtex_bibfiles = ['my-references.bib']

Afterwards all the references defined in the bibliography file(s) can be used throughout the Jupyter notebooks and other source files as detailed in the following.


You can create citations like [PGH11]:


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

You can create a list of references in any reStructuredText file (or reST cell in a notebook) like this:

.. bibliography::

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

The list of references may look something like this (in HTML output):


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.


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.