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. See this section.


foo (str) – Example string parameter


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


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.


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 (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.

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

There is an alternative Sphinx extension for creating bibliographies: However, this project seems to be abandoned (last commit in 2011).

Thumbnail Galleries

With nbsphinx you can create thumbnail galleries in notebook files as described in Creating Thumbnail Galleries.

If you like, you can also create such galleries in reST files using the nbgallery directive.

It takes the same parameters as the toctree directive.


The notes regarding LaTeX in Creating Thumbnail Galleries and Using toctree In A Notebook also apply here!

The following example gallery was created using:

.. nbgallery::
    :caption: This is a thumbnail gallery:
    :name: rst-gallery