This page was generated from doc/prolog-and-epilog.ipynb. Interactive online version: Binder badge

Prolog and Epilog

When including notebooks in your Sphinx documentation, you can choose to add some generic content before and after each notebook. This can be done with the configuration values nbsphinx_prolog and nbsphinx_epilog in the file conf.py.

The prolog and epilog strings can hold arbitrary reST markup. Particularly, the only and raw directives can be used to have different content for HTML and LaTeX output.

Those strings are also processed by the Jinja2 templating engine. This means you can run Python-like code within those strings. You have access to the current Sphinx build environment via the variable env. Most notably, you can get the file name of the current notebook with

{{ env.doc2path(env.docname, base=None) }}

Have a look at the Jinja2 template documentation for more information.

Warning:

If you use invalid syntax, you might get an error like this:

jinja2.exceptions.TemplateSyntaxError: expected token ':', got '}'

This is especially prone to happen when using raw LaTeX, with its abundance of braces. To avoid clashing braces you can try to insert additional spaces or LaTeX macros that don’t have a visible effect, like e.g. \strut{}. For example, you can avoid three consecutive opening braces with something like that:

\texttt{\strut{}{{ env.doc2path(env.docname, base=None) }}}

NB: The three consecutive closing braces in this example are not problematic.

Examples

You can include a simple static string, using reST markup if you like:

nbsphinx_epilog = """
----

Generated by nbsphinx_ from a Jupyter_ notebook.

.. _nbsphinx: http://nbsphinx.readthedocs.io/
.. _Jupyter: https://jupyter.org/
"""

Using some additional Jinja2 markup and the information from the env variable, you can create URLs that point to the current notebook file, but located on some other server:

nbsphinx_prolog = """
Go there: https://example.org/notebooks/{{ env.doc2path(env.docname, base=None) }}

----
"""

You can also use separate content for HTML and LaTeX output, e.g.:

nbsphinx_prolog = """
{% set docname = env.doc2path(env.docname, base=None) %}

.. only:: html

    Go there: https://example.org/notebooks/{{ docname }}

.. only:: latex

    The following section was created from :file:`{{ docname }}`.
"""

For a more involved example for different HTML and LaTeX versions, see the file conf.py of the nbsphinx documentation.