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_.
.. _Sphinx hyperlinks: https://www.sphinx-doc.org/en/master/usage/
restructuredtext/basics.html#external-links
.. _link: subdir/a-notebook-in-a-subdir.ipynb
.. code-block:: rst
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`_.
.. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb
.. code-block:: rst
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!
.. _anonymous hyperlink target: https://docutils.sourceforge.io/docs/ref/rst/
restructuredtext.html#anonymous-hyperlinks
__ subdir/a-notebook-in-a-subdir.ipynb
.. code-block:: rst
like this: link__.
__ subdir/a-notebook-in-a-subdir.ipynb
Finally, you can use `Embedded URIs`_, like this
`link `_.
.. _Embedded URIs: https://docutils.sourceforge.io/docs/ref/rst/
restructuredtext.html#embedded-uris-and-aliases
.. code-block:: rst
like this `link `_.
.. 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_.
.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section
.. code-block:: rst
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:
:ref:`/subdir/a-notebook-in-a-subdir.ipynb`.
.. code-block:: rst
:ref:`/subdir/a-notebook-in-a-subdir.ipynb`
But you can also provide
:ref:`your own link title `.
.. code-block:: rst
:ref:`your own link title `
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.
:ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section`
(the subsection title is used as link text) and
:ref:`alternative text `.
These links were created with:
.. code-block:: rst
:ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section`
:ref:`alternative text `
.. 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
----------------------------------------
.. nbwarning::
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:
.. nbinfo::
Note
This is an info box.
It may include nested formatting, even another info/warning box:
.. nbwarning:: **Warning:** You should probably not use nested boxes!
Domain Objects
--------------
.. py:function:: example_python_function(foo)
This is just for testing domain object links.
:param str foo: Example string parameter
.. seealso::
:ref:`/markdown-cells.ipynb#Links-to-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:
.. code-block:: python
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.
.. _standard Sphinx Citations: https://www.sphinx-doc.org/en/master/usage/
restructuredtext/basics.html#citations
.. _sphinxcontrib.bibtex: https://sphinxcontrib-bibtex.readthedocs.io/
Citations
^^^^^^^^^
You can create citations like :cite:`perez2011python`:
.. code-block:: rst
:cite:`perez2011python`
You can also create so-called in-text citations,
where the names of the authors, for example :cite:t:`perez2011python`,
are part of the sentence:
.. code-block:: rst
: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:
.. code-block:: rst
.. 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 :footcite:`perez2011python`.
.. code-block:: rst
:footcite:`perez2011python`
In-text citations like :footcite:t:`kluyver2016jupyter` can be created like this:
.. code-block:: rst
: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
.. code-block:: rst
.. footbibliography::
directive. For example, a footnote bibliography might
look like this (in HTML output):
.. footbibliography::
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:
.. code-block:: rest
.. nblinkgallery::
:caption: A few links
:name: rst-link-gallery
gallery/multiple-outputs
gallery/no-thumbnail
gallery/cell-metadata
orphan
.. nblinkgallery::
:caption: A few links
:name: rst-link-gallery
gallery/multiple-outputs
gallery/no-thumbnail
gallery/cell-metadata
orphan
.. seealso::
`Link Galleries in Jupyter Notebooks `_
Thumbnail Galleries
-------------------
With ``nbsphinx`` you can create thumbnail galleries in notebook files
as described in :ref:`/gallery/gallery-with-nested-documents.ipynb`.
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.
__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/
directives.html#directive-toctree
.. note::
The notes regarding LaTeX in :ref:`/gallery/gallery-with-nested-documents.ipynb`
and :ref:`/subdir/toctree.ipynb` also apply here!
The following example gallery was created using:
.. code-block:: rest
.. nbgallery::
:caption: This is a thumbnail gallery:
:name: rst-gallery
:glob:
:reversed:
gallery/*-rst
.. nbgallery::
:caption: This is a thumbnail gallery:
:name: rst-gallery
:glob:
:reversed:
gallery/*-rst