Setting up LaTeX templates for Jupyter notebook

There is a great tool for training / reporting / writing smart books about code - Jupyter Notebook . If a report or a book, for example, is written in Cyrillic, and you need to quickly make a PDF from it with beautiful formulas and a dash of the correct length, then you immediately find a problem: in the standard template that Jupyter uses to convert notepads to PDF via LaTeX, there are no packages needed with the necessary parameters, so LaTeX just does not compile and you can’t get a PDF.

Permanent assumptions: we will talk about Jupyter, which disconnected from the main IPython project in the IPython 4 release; if you want to talk about IPython 3.x, replace the commands jupyterwith ipythonand check for possible file name mismatches. To generate PDF, we use either the command line (jupyter nbconvert --to pdf myfile.ipynb), or a button from the web interface Download as -> PDF via LaTeX.

The easiest way to solve the problem with missing packages is  jupyter nbconvert --to latex myfile.ipynbto open the resulting TeX source and add the missing packages. We compile the source ( pdflatex myfile.texor whatever someone likes), the goal is achieved.

If the problem is not solved in one line (you need to seriously change the template and do not want to delve into the unpleasant result of converting to LaTeX) / I have many notebooks / I want a more general solution, then continue.

TL; DR : in order to get pdf with the Cyrillic alphabet, add two files to yourself (the link leads to a comment with a short description).

It is necessary to explain to the converter that to convert a notepad into LaTeX, it should not use a standard template, but ours, with an expanded header, the most correct font and corporate theme.

jupyter nbconvert --to pdf --template mytemplate.tplx myfile.ipynb

Problems: mytemplate.tplxit is successfully located only in the directory from where it is launched nbconvert; it is not possible to drag this through the web interface; how to write a template is unclear.

Settings files

First, about the configuration and location of the files. This is quickly solved by writing your own settings file. The settings file for nbconvert  is a Python code file. How to specify the settings file when calling the converter:

jupyter nbconvert --to pdf --config cfg.py myfile.ipynb

The settings file looks something like this:

c = get_config()
c.NbConvertApp.export_format = 'pdf'
c.TemplateExporter.template_path = ['.']
c.Exporter.template_file = 'article'

Here export_formatis the default value for --to, template_pathis the list of directories with templates, here it says that template files should be searched in the directory where nbconvert is launched from, it template_filemeans that, unless otherwise specified, you need to use the template article.tplx.

Now if you run jupyter notebook --config cfg.py, then all the settings for the conversion will be taken first from the configuration file, which is what we need. If you want these settings to be the default at any start by nbconvertthis user, you need to put them in a file ~/.jupyter/jupyter_nbconvert_config.py. Accordingly, for the notebookgeneral settings file -  ~/.jupyter/jupyter_notebook_config.py.

Patterns

The most interesting part is how to write templates. Templates are written using the Jinja2 template engine ; to avoid conflicts with special LaTeX characters, the service sequences of the template engine are redefined  (the first is {replaced by ((, the others {by (, with back brackets mirror). The default set of templates is located at NBCONVERT_INSTALLATION_DIR/nbconvert/templates/latex/. They are well documented, it makes sense to inherit from them when creating your own templates. More sample templates are in the nbconvert-examples repository on Github . Screenshots of various design options can be found in readme to one of the sections of this repository.

How to write your own template in which all the things you personally need will be performed? Create a file mytemplate.tplxin which to write a few necessary things.

Firstly, carefully inherit from a template that defines a specific style of drawing cells with code ( as in the example ):

% Default to the notebook output style
((* set cell_style = 'style_notebook.tplx' *))
% Inherit from the specified cell style.
((* extends cell_style *))

Here I inherit from a template style_notebook.tplxthat is not standard, but lies in nbconvert-examples . This template is also written, apparently, for the old version of nbconvert, so in it you will need to change the line ((* extends 'latex_base.tplx' *))to ((* extends 'base.tplx' *)).

Secondly, to determine the \documentclassfuture LaTeX file and not make a header (you can instead write code that takes a header from the file metadata .ipynbor from somewhere else):

((* block docclass *))
\documentclass{article}
((* endblock docclass *))
((* block maketitle *))((* endblock maketitle *))

Thirdly, connect the desired packages with Cyrillic support (and a dozen or two more of your favorite):

((* block packages *))
((( super() ))) % load all other packages
\usepackage[T2A]{fontenc}
\usepackage[english, russian]{babel}
\usepackage{mathtools}
((* endblock packages *))

A complete list of blocks is described in nbconvert/templates/latex/skeleton/null.tplx and nbconvert/templates/latex/base.tplx(and these are also links to GitHub).

If we want to use the resulting template not in a specific project, but in all notebooks, we can put it, for example, in ~/.jupyter/templates/and change the corresponding line in the settings file (thanks to spitty for the remark that relative paths will not work just like that):

import os
c.TemplateExporter.template_path = ['.', os.path.expanduser('~/.jupyter/templates/')]

After minor corrections in the template for rendering cells with code (I did not like the inscriptions In [*]), I got these reports (screenshot from a PDF file):