DOC: Mention \nbsphinxstartnotebook and \nbsphinxstopnotebook

doc/conf.py

@@ -63,20 +63,18 @@
 
 .. raw:: latex
 
-    \nbsphinxstartnotebook{\scriptsize\strut
+    \nbsphinxstartnotebook{\scriptsize\noindent\strut
     \textcolor{gray}{The following section was generated from
-       {\sphinxcode{\sphinxupquote{\strut{}{{ docname | escape_latex }}}}}\relax
-        \dotfill }}
+    \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}}
 """
 
 # This is processed by Jinja2 and inserted after each notebook
 nbsphinx_epilog = r"""
 .. raw:: latex
 
-    \nbsphinxstopnotebook{\scriptsize
-    \noindent\strut\textcolor{gray}{\dotfill\sphinxcode{\sphinxupquote{\relax
-    {{ env.doc2path(env.docname, base='doc') | escape_latex }}}}
-    ends here.}}
+    \nbsphinxstopnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{\dotfill\ \sphinxcode{\sphinxupquote{\strut
+    {{ env.doc2path(env.docname, base='doc') | escape_latex }}}} ends here.}}
 """
 
 # Input prompt for code cells. "%s" is replaced by the execution count.

doc/prolog-and-epilog.ipynb

@@ -92,19 +92,30 @@
     "You can also use separate content for HTML and LaTeX output, e.g.:\n",
     "\n",
     "```python\n",
-    "nbsphinx_prolog = \"\"\"\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",
-    ".. only:: latex\n",
+    ".. raw:: latex\n",
     "\n",
-    "    The following section was created from :file:`{{ docname }}`.\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."
    ]
   }
@@ -125,7 +136,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.7rc1"
+   "version": "3.6.7"
   }
  },
  "nbformat": 4,