JTEX is a command line tool (CLI) for rendering LaTeX documents from jinja-style templates.

Related tags

Documentationjtex
Overview

JTEX

JTEX is a command line tool (CLI) for rendering LaTeX documents from jinja-style templates. This package uses Jinja2 as the template engine with a modified environment and syntax that plays well with LaTeX's markup.

This allows you to build LaTeX documents driven by content, data and a template. We built this package while developing our template based PDF/LaTeX export system for Curvenote, where it is used to create documents from the templates on the Curvenote Community Template Repo.

Installation

Install the package into your virtual environment using pip:

  pip install jtex

and confirm correct installation by typing:

  jtex --version

An example

As we are dealing with content and data, the cli accepts paths to specific files or folders rather than accepting arguments inline. Here is a minimal example:

Given these 3 files:

# data.yml
title: Exploring Outer Space
author:
  name: Ana Space
  email: [email protected]
% content.tex
Outer space is the expanse that exists beyond Earth and between celestial bodies. Outer space is not completely empty—it is a hard vacuum containing a low density of particles, predominantly a plasma of hydrogen and helium, as well as electromagnetic radiation, magnetic fields, neutrinos, dust, and cosmic rays.
% template.tex
\documentclass{article}

\title{[-title-]}
\author{[-author.name-] ([-author.email-])}

\begin{document}
\maketitle

[-CONTENT-]
\vskip 1cm
The End!
\end{document}

We can render a LaTeX document with the following command:

  jtex build-lite output.tex data.yml content.tex template.tex

To produce a .tex file with the following contents:

% output.tex
\documentclass{article}

\title{Exploring Outer Space}
\author{Ana Space ([email protected])}

\begin{document}
\maketitle

% content.tex
Outer space is the expanse that exists beyond Earth and between celestial bodies. Outer space is not completely empty—it is a hard vacuum containing a low density of particles, predominantly a plasma of hydrogen and helium, as well as electromagnetic radiation, magnetic fields, neutrinos, dust, and cosmic rays.
\vskip 1cm
The End!
\end{document}

Which when compiled produces the following document:

The document layout is flexible and will be based on structure provided in the template.tex file, where the modified jinja syntax ([-, -]) is used to expand variables from the matching DocModel provided in data.yml.

[-CONTENT-] is a special variable that will expand to the entire contents of content.tex

This example only shows variable expansion ([-myvar-]) but the full jinja2 environment is available with control flow, filters and many python commands.

The build-lite command shown above is not opinionated and can be used to render any template with a matching DocModel data structure.

CLI Overview

Get help from the command line tool at any time using the --help option.

  jtex --help

Note: the CLI uses typer which provides shell completion option as standard. These are list in help messages and installation is recommended, but these commands are not central to use of the tool.

Command overview

The following commands are available on the cli.

build-lite

build-lite is an un-opinionated rendering command which as in the example above will allow you to render any template given content and a DocModel.

jtex build-lite --help

Usage: jtex build-lite [OPTIONS] DATA_YML TEMPLATE_TEX OUTPUT_TEX

Arguments:
  DATA_YML       Path to a YAML file containing the DocModel (a free-form
                 dict) required to render the template.  [required]
  TEMPLATE_TEX   Path to a file with a compatible LaTeX template e.g.
                 mytemplate.tex. The template should align with the data
                 structure given by the DocModel  [required]
  OUTPUT_TEX     Name of a local file to write the rendered content to. If
                 OUTPUT exists it will be replaced.  [required]

Options:
  --content FILE          Path to a file containing the content to render in
                          the [-CONTENT-] variable  [required]
  --bib FILE              Path to an optional bib file. This will be copied as-
                          is into the target folder.
  --lipsum / --no-lipsum  If specified will patch the document with
                          '\usepackage{lipsum}'. Useful in testing where
                          `content.tex` or `temaplte.tex` uses the lipsum
                          package.  [default: no-lipsum]
  --help                  Show this message and exit.

The "DocModel" in this case is a bit of an overstatement as it is just a free-form python dictionary defined in the data.yml file as shown above.

As you build your template, you can decide on the structure of the data in this file and keep it aligned with the variables you access from within the template. To find out more see Creating Templates

build

build is an opinionated rendering command intended for use with Curvenote content and templates specifically.

jtex build --help

Usage: jtex build [OPTIONS] CONTENT_PATH OUTPUT_PATH

Arguments:
  CONTENT_PATH  Path to a folder with containing data and content to render.
                The folder should contain the following files: data.yml,
                main.tex, main.bib - along with any additional graphics assets
                [required]
  OUTPUT_PATH   Path to a folder in which to construct the Latex assets. If
                OUTPUT_PATH exists it and all files will be removed and a new
                empty folder created  [required]

Options:
  --template-path DIRECTORY  Path to a Curvenote compatible LaTeX template
                             folder. This is intended for use with local
                             Curvenote templates or in template
                             development. Omitting this option will use the
                             built in template.
  --template-name TEXT       Name of a Curvenote template available from the
                             public Curvenote API. (e.g. 'default').
                             Specifying template-path will override this
                             option if both are provided.
  --lipsum / --no-lipsum     If lipsum, will patch the document with
                             '\usepackage{lipsum}'. Useful when testing
                             templates, where `content.tex` uses the lipsum
                             package.  [default: no-lipsum]
  --strict / --no-strict     If strict, then missing required tagged content
                             or options will halt the process.  [default: no-
                             strict]
  --copy / --no-copy         Should image assets will be copied into the
                             target folder?  [default: copy]
  --help                     Show this message and exit.

When exporting LaTeX from Curvenote's API custom environments and commands are included by default. These require certain packages to be loaded and definitions to be included in the final document. build will include these definition files and expect certain structure to be present in the DocModel when rendering.

As build is not generally applicable outside of Curvenote templates, we'll not discuss the details further here. For more information check the Curvenote Open Template Repo.

Note: The Curvenote API can also respond with vanilla LaTeX, but this is not the default case for rendering. For more information on programmatically accessing the Curvenote API, see the Curvenote python client.

validate

validate is a dry run command which will validate a Curvenote template. This is very simple validation at the moment and we expect this to be extended.

jtex validate --help

Usage: jtex validate [OPTIONS] TEMPLATE_PATH

Arguments:
  TEMPLATE_PATH  Local folder containing the Curvenote compatible template to
                 validate  [required]

Creating Templates

This cli tool uses a customized jinja2 environment. We explain the custom syntax below and how to use that in conjunction with the content.tex and data.yml files in a bit more detail than shown in the previous example.

However, to get the most out of this tool, understanding how jinja2 works and the features it provides will help a lot. The Jinja Template Designer Documentation is a great resource, covering all the features of the jinja2 language in the context of HTML rendering and the standard jinja2 syntax.

That guide along with the information included below for LaTeX rendering and our custom syntax should give you everything you need to know to produce your own templates.

Jinja

About jinja templates:

A template contains variables and/or expressions, which get replaced with values when a template is rendered; and tags, which control the logic of the template. The template syntax is heavily inspired by Django and Python.

The cli uses a jinja2 environment with the following modifications.

Syntax

customized standard jinja2
Statements [# #] {% %}
Expressions [- -] {{ }}
Comments %# #% {# #}

A minimal LaTeX example illustrating these would be:

\documentclass{article}
\begin{document}
\section{Famous People}
%# Print a list of famous people defined in the context dictionary #%
\begin{itemize}
[# for person in famous_people #]
\item [-person.name-], [-person.job-] [# if person.email #]([-person.email-])[# endif #]
[# endfor #]
\end{itemize}
\end{document}

Which will print out a list of famous people's names, jobs and emails, if we have them.

Other environment differences

In addition to the custom syntax we also set the following options:

option our setting jinja default effect
trim_blocks True False If this is set to True the first newline after a block is removed (block, not variable tag!)
autoescape False True If set to False the XML/HTML autoescaping feature is disabled
auto_reload True False Will always check template location for changes and recompiles the template as needed
undefined SlientUndefined None Ignore any undefined variables in the template, render anyways without affected blocks or variables
keep_trailing_newline True False Preserve the trailing newline when rendering templates, important in LaTeX

jinja provide a whole host of functions, tests and filters at global scope. We have extended further this by adding the python __builtins__ providing additional commonly used python functions within the jinja rendering context.

Building a DocModel

We use the term DocModel in our documentation to refer to the dictionary of data passed to a jinja template for rendering, loaded from a data.yml file. jinja docs call this the Context Dictionary. It is easy to relate this to the yml file that you need to create to use the cli.

The fields at the root level of the file are available as variables in the jinja context at global scope.

# data.yml
title: Outer Space
author: Ana Cosmo

% template.tex
...
\title{[-title-]}
\author{[-author-]}
...

You can add comments to your template, and these will be removed at render time. Just in case, the comments are also valid LaTeX comments so should not affect your build even if one did leak through

  % template.tex

  % this is a LaTeX comment
  %# this is a template comment and will be removed at render, but it is also a valid LaTeX comment #%

These variables themselves can be nested data structures of dictionaries, lists, strings, numbers and booleans

# data.yml
authors:
  - name: Ana Cosmo
    email: [email protected]
  - name: Bill Saturn
    email: [email protected]
tags:
  - space
  - planets
  - cosmos

% template.tex
...
[# for author in authors #]
\author{[-author.name-] ([-author.email-])}
[# endfor #]

The first author is [-authors[0].name-]
The last author is [-authors[-1].name-]

tags: [-tags|join(', ')-]

%# main content goes here #%
[-CONTENT-]
...

[-CONTENT-] is a special variable that will expand to the entire contents of content.tex

We'll not go into more jinja features here, as they are covered in the Jinja Template Designer Documentation -- simply replace the standard jinja syntax with our customized syntax and bear in mind the rules of LaTeX and constructing sophisticated templates is pretty straightforward with practice.

Curvenote Templates

To look at some of the templates we've developed at Curvenote, or for documentation on how to create template for Curvenote please visit the Open Template Repo and check the documentation there.

We use this cli tool for development, testing and validation of any template submitted to that repo.

Owner
Curvenote
Write, share and communicate interactive scientific content in a collaborative environment.
Curvenote
Official Matplotlib cheat sheets

Official Matplotlib cheat sheets

Matplotlib Developers 6.7k Jan 09, 2023
DeltaPy - Tabular Data Augmentation (by @firmai)

DeltaPy⁠⁠ — Tabular Data Augmentation & Feature Engineering Finance Quant Machine Learning ML-Quant.com - Automated Research Repository Introduction T

Derek Snow 470 Dec 28, 2022
Sms Bomber, Tool Encryptor

ɴᴏʙɪᴛᴀシ︎ ғᴏʀ ᴀɴʏ ʜᴇʟᴘシ︎ Install pkg install git -y pkg install python -y pip install requests git clone https://github.com/AK27HVAU/akash Run cd Akash

ɴᴏʙɪᴛᴀシ︎ 4 May 23, 2022
A simple document management REST based API for collaboratively interacting with documents

documan_api A simple document management REST based API for collaboratively interacting with documents.

Shahid Yousuf 1 Jan 22, 2022
Resource hub for Obsidian resources.

Obsidian Community Vault Welcome! This is an experimental vault that is maintained by the Obsidian community. For best results we recommend downloadin

Obsidian Community 320 Jan 02, 2023
300+ Python Interview Questions

300+ Python Interview Questions

Pradeep Kumar 1.1k Jan 02, 2023
[Unofficial] Python PEP in EPUB format

PEPs in EPUB format This is a unofficial repository where I stock all valid PEPs in the EPUB format. Repository Cloning git clone --recursive Mickaël Schoentgen 9 Oct 12, 2022

Crystal Smp plugin for show scoreboards

MCDR-CrystalScoreboards Crystal plugin for show scoreboards | Only 1.12 Usage !!s : Plugin help message !!s hide : Hide scoreboard !!s show : Show Sco

CristhianCd 3 Oct 12, 2021
PySpark Cheat Sheet - learn PySpark and develop apps faster

This cheat sheet will help you learn PySpark and write PySpark apps faster. Everything in here is fully functional PySpark code you can run or adapt to your programs.

Carter Shanklin 168 Jan 01, 2023
Feature Store for Machine Learning

Overview Feast is an open source feature store for machine learning. Feast is the fastest path to productionizing analytic data for model training and

Feast 3.8k Dec 30, 2022
Version bêta d'un système pour suivre les prix des livres chez Books to Scrape,

Version bêta d'un système pour suivre les prix des livres chez Books to Scrape, un revendeur de livres en ligne. En pratique, dans cette version bêta, le programme n'effectuera pas une véritable surv

Mouhamed Dia 1 Jan 06, 2022
Dynamic Resume Generator

Dynamic Resume Generator

Quinten Lisowe 15 May 19, 2022
Reproducible Data Science at Scale!

Pachyderm: The Data Foundation for Machine Learning Pachyderm provides the data layer that allows machine learning teams to productionize and scale th

Pachyderm 5.7k Dec 29, 2022
This is the data scrapped of all the pitches made up potential startup's to established bussiness tycoons of India with all the details of Investments made, equity share, Name of investor etc.

SharkTankInvestor This is the data scrapped of all the pitches made up potential startup's to established bussiness tycoons of India with all the deta

Subradip Poddar 2 Aug 02, 2022
Proyecto - Desgaste y rendimiento de empleados de IBM HR Analytics

Acceder al código desde Google Colab para poder ver de manera adecuada todas las visualizaciones y poder interactuar con ellas. Links de acceso: Noteb

1 Jan 31, 2022
Members: Thomas Longuevergne Program: Network Security Course: 1DV501 Date of submission: 2021-11-02

Mini-project report Members: Thomas Longuevergne Program: Network Security Course: 1DV501 Date of submission: 2021-11-02 Introduction This project was

1 Nov 08, 2021
Python Programming (Practical) (1-25) Download 👇🏼

BCA-603 : Python Programming (Practical) (1-25) Download zip 🙂 🌟 How to run programs : Clone or download this repo to your computer. Unzip (If you d

Milan Jadav 2 Jun 02, 2022
Build AGNOS, the operating system for your comma three

agnos-builder This is the tool to build AGNOS, our Ubuntu based OS. AGNOS runs on the comma three devkit. NOTE: the edk2_tici and agnos-firmare submod

comma.ai 21 Dec 24, 2022
Tampilan - Change Termux Appearance With Python

Tampilan Gambar usage pkg update && pkg upgrade pkg install git && pkg install f

Creator Lord-Botz 1 Jan 31, 2022
Course materials for: Geospatial Data Science

Course materials for: Geospatial Data Science These course materials cover the lectures for the course held for the first time in spring 2022 at IT Un

Michael Szell 266 Jan 02, 2023