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
For now, there are two directives available:
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!
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:
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 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).