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.