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 olddocutils
.
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¶
References¶
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 conf.py
and select the BibTeX file(s) you want to use:
extensions = [
'nbsphinx',
'sphinxcontrib.bibtex',
# Probably more extensions here ...
]
bibtex_bibfiles = ['my-references.bib']
bibtex_reference_style = 'author_year'
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.
Citations¶
You can create citations like [Pérez et al., 2011]:
:cite:`perez2011python`
You can also create so-called in-text citations, where the names of the authors, for example Pérez et al. [2011], are part of the sentence:
:cite:t:`perez2011python`
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::
For an example, see the file doc/references.rst
.
Footnote citations¶
With a sphinxcontrib.bibtex version of >= 2.0.0
it is
possible to create footnote bibliographies with footnote
citations like [1].
:footcite:`perez2011python`
In-text citations like Kluyver et al.[2] can be created like this:
:footcite:t:`kluyver2016jupyter`
Also footnote citations can be used within Jupyter notebooks with a special HTML syntax, see the section about footnote citations in Markdown cells. Footnote citations are restricted to their own source file and the assembly of the bibliography is (analogously to normal citations) invoked with the
.. footbibliography::
directive. For example, a footnote bibliography might look like this (in HTML output):
In the LaTeX/PDF output, there is no list of references appearing right here. Instead, the footnote citations are placed into the footnotes of their respective pages.
Thumbnail Link Galleries (HTML only)¶
In some case it is desired to create thumbnail links to existing notebooks,
already included in a toctree
. This can be used e.g. to link to a subset
of notebooks from API documentation to highlight the use of some functionality.
For this there is a dedicated nblinkgallery
directive.
The following example gallery was created using:
.. nblinkgallery::
:caption: A few links
:name: rst-link-gallery
gallery/multiple-outputs
gallery/no-thumbnail
gallery/cell-metadata
orphan
See also
Thumbnail Galleries¶
With nbsphinx
you can create thumbnail galleries in notebook files
as described in Gallery With Nested Documents.
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.
Note
The notes regarding LaTeX in Gallery With Nested Documents 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
:glob:
:reversed:
gallery/*-rst