Create different documents from the same sources using Jinja

Specialist technique

This tutorial applies build-time conditional text (profiling) to a reStructuredText toolchain, using a Python preprocessing script. The principle, generating several document variants from one source, applies to other formats; for DITA XML’s equivalent, see the NuFirewall case study.

Objective

The profiling.py Python script below allows you to profile content in preprocessing using the powerful Jinja template engine. For a more complex variant using object-oriented classes, see creating different documents via Jinja (object method). You can also generate documents directly from ReST conditional text without a separate preprocessing step.

#!/usr/bin/env python3
import jinja2
import sys

public=str(sys.argv[1])
env = jinja2.Environment(loader=jinja2.FileSystemLoader('./'))
template = env.get_template('conditional-text.rst')
string=template.render(audience=public)

file = open('conditional-text-output.rst','w')
file.write(string)
file.close()

Contents of the file conditional-text.rst:

Using conditional text
=================================

{% if audience=='electrician' %}

.. admonition:: Danger for electricians

   Risk of electrocution

   Do not touch electrical wires.

{% else %}

.. admonition:: Danger for plumbers

   Risk of drowning

   Do not dive into the pool.

{% endif %}

How to use:

./profiling.py electrician

Now, just call the script before compiling via Sphinx in the Makefile.

Related articles

• Automatically insert data into a reStructuredText file
• Regular expressions in Python
• sed: modify your text without opening your files