This notebook is part of the nbsphinx
documentation: https://nbsphinx.readthedocs.io/.
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.
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.