doc/prolog-and-epilog.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Prolog and Epilog\n",
    "\n",
    "When including notebooks in your Sphinx documentation, you can choose to add some generic content before and after each notebook.\n",
    "This can be done with the configuration values `nbsphinx_prolog` and `nbsphinx_epilog` in the file `conf.py`.\n",
    "\n",
    "The prolog and epilog strings can hold arbitrary [reST](https://www.sphinx-doc.org/rest.html) markup.\n",
    "Particularly, the [only](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only) and [raw](https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through) directives can be used to have different content for HTML and LaTeX output.\n",
    "\n",
    "Those strings are also processed by the [Jinja2](https://jinja.palletsprojects.com/) templating engine.\n",
    "This means you can run Python-like code within those strings.\n",
    "You have access to the current [Sphinx build environment](https://www.sphinx-doc.org/en/master/extdev/envapi.html) via the variable `env`.\n",
    "Most notably, you can get the file name of the current notebook with\n",
    "\n",
    "    {{ env.doc2path(env.docname, base=None) }}\n",
    "\n",
    "Have a look at the [Jinja2 template documentation](https://jinja.palletsprojects.com/templates/) for more information.\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "Warning\n",
    "\n",
    "If you use invalid syntax, you might get an error like this:\n",
    "\n",
    "    jinja2.exceptions.TemplateSyntaxError: expected token ':', got '}'\n",
    "\n",
    "This is especially prone to happen when using raw LaTeX, with its abundance of braces.\n",
    "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{}`.\n",
    "For example, you can avoid three consecutive opening braces with something like that:\n",
    "\n",
    "    \\texttt{\\strut{}{{ env.doc2path(env.docname, base=None) }}}\n",
    "\n",
    "NB: The three consecutive closing braces in this example are not problematic.\n",
    "    \n",
    "An alternative work-around would be to surround LaTeX braces with Jinja braces like this:\n",
    "    \n",
    "    {{ '{' }}\n",
    "    \n",
    "The string within will not be touched by Jinja.\n",
    "\n",
    "Another special Jinja syntax is `{%`, which is also often used in fancy TeX/LaTeX code.\n",
    "A work-around for this situation would be to use\n",
    "    \n",
    "    {{ '{%' }}\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples\n",
    "\n",
    "You can include a simple static string, using [reST](https://www.sphinx-doc.org/rest.html) markup if you like:\n",
    "\n",
    "```python\n",
    "nbsphinx_epilog = \"\"\"\n",
    "----\n",
    "\n",
    "Generated by nbsphinx_ from a Jupyter_ notebook.\n",
    "\n",
    ".. _nbsphinx: https://nbsphinx.readthedocs.io/\n",
    ".. _Jupyter: https://jupyter.org/\n",
    "\"\"\"\n",
    "```\n",
    "\n",
    "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:\n",
    "\n",
    "```python\n",
    "nbsphinx_prolog = \"\"\"\n",
    "Go there: https://example.org/notebooks/{{ env.doc2path(env.docname, base=None) }}\n",
    "\n",
    "----\n",
    "\"\"\"\n",
    "```\n",
    "\n",
    "You can also use separate content for HTML and LaTeX output, e.g.:\n",
    "\n",
    "```python\n",
    "nbsphinx_prolog = r\"\"\"\n",
    "{% set docname = env.doc2path(env.docname, base=None) %}\n",
    "\n",
    ".. only:: html\n",
    "\n",
    "    Go there: https://example.org/notebooks/{{ docname }}\n",
    "\n",
    ".. raw:: latex\n",
    "\n",
    "    \\nbsphinxstartnotebook{The following section was created from\n",
    "    \\texttt{\\strut{}{{ docname }}}:}\n",
    "\"\"\"\n",
    "\n",
    "nbsphinx_epilog = r\"\"\"\n",
    ".. raw:: latex\n",
    "\n",
    "    \\nbsphinxstopnotebook{\\hfill End of notebook.}\n",
    "\"\"\"\n",
    "```\n",
    "\n",
    "Note the use of the `\\nbsphinxstartnotebook` and `\\nbsphinxstopnotebook` commands.\n",
    "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\".\n",
    "They also avoid page breaks, in order for the \"prolog\"/\"epilog\" not to end up on the page before/after the notebook.\n",
    "\n",
    "For a more involved example for different HTML and LaTeX versions, see the file [conf.py](conf.py) of the `nbsphinx` documentation."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}