Shortcuts
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.

An alternative work-around would be to surround LaTeX braces with Jinja braces like this:

{{ '{' }}

The string within will not be touched by Jinja.

Another special Jinja syntax is {%, which is also often used in fancy TeX/LaTeX code. A work-around for this situation would be to use

{{ '{%' }}

Examples

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

nbsphinx_epilog = """
----

Generated by nbsphinx_ from a Jupyter_ notebook.

.. _nbsphinx: https://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 = r"""
{% set docname = env.doc2path(env.docname, base=None) %}

.. only:: html

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

.. raw:: latex

    \nbsphinxstartnotebook{The following section was created from
    \texttt{\strut{}{{ docname }}}:}
"""

nbsphinx_epilog = r"""
.. raw:: latex

    \nbsphinxstopnotebook{\hfill End of notebook.}
"""

Note the use of the \nbsphinxstartnotebook and \nbsphinxstopnotebook commands. Those make sure there is not too much space between the “prolog” and the beginning of the notebook and, respectively, between the end of the notebook and the “epilog”. They also avoid page breaks, in order for the “prolog”/”epilog” not to end up on the page before/after the notebook.

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

Read the Docs v: pytorch-theme
Versions
latest
0.7.1
0.7.0
0.6.1
0.6.0
0.5.1
0.5.0
0.4.3
0.4.2
0.4.1
0.3.5
0.3.4
0.3.3
0.3.2
0.3.1
0.3.0
0.2.18
0.2.17
0.2.16
0.2.15
0.2.14
0.2.13
0.2.12
0.2.11
0.2.10
0.2.9
0.2.8
0.2.7
0.2.6
0.2.5
0.2.4
0.2.3
0.2.2
0.2.1
0.2.0
typlog-theme
traditional-theme
sphinxdoc-theme
sphinx-book-theme
sizzle-theme
scrolls-theme
rtd-theme
pyviz-theme
pytorch-theme
pyramid-theme
pydata-theme
py3doc-enhanced-theme
pangeo-theme
pandas-theme
nature-theme
material-theme
maisie-theme
jupyter-theme
haiku-theme
guzzle-theme
dask-theme
cloud-theme
classic-theme
bootstrap-theme
bizstyle-theme
better-theme
basicstrap-theme
astropy-theme
alabaster-theme
agogo-theme
0.1.0
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.

Docs

Lorem ipsum dolor sit amet, consectetur

View Docs

Tutorials

Lorem ipsum dolor sit amet, consectetur

View Tutorials

Resources

Lorem ipsum dolor sit amet, consectetur

View Resources