matrix-doc/scripts/templating

This folder contains the templates and a home-brewed templating system called Batesian for creating the spec. Batesian uses the templating system Jinja2 in Python.

Installation

 $ pip install Jinja2

Running

To pass arbitrary files (not limited to RST) through the templating system:

 $ python build.py -i matrix_templates /random/file/path/here.rst

The template output can be found at out/here.rst. For a full list of options, type python build.py --help.

Developing

Sections and Units

Batesian is built around the concept of Sections and Units. Sections are strings which will be inserted into the provided document. Every section has a unique key name which is the template variable that it represents. Units are arbitrary python data. They are also represented by unique key names.

Adding template variables

If you want to add a new template variable e.g. {{foo_bar}} which is replaced with the text foobar, you need to add a new Section:

• Open matrix_templates/sections.py.

• Add a new function to MatrixSections called render_foo_bar. The function name after render_ determines the template variable name, and the return value of this function determines what will be inserted.

  def render_foo_bar(self):
      return "foobar"
  

• Run build.py with a file which has {{foo_bar}} in it, and it will be replaced with foobar.

Adding data for template variables

If you want to expose arbitrary data which can be used by MatrixSections, you need to add a new Unit:

• Open matrix_templates/units.py.

• Add a new function to MatrixUnits called load_some_data. Similar to sections, the function name after load_ determines the unit name, and the return value of this function determines the value of the unit.

  def load_some_data(self):
      return {
         "data": "this could be JSON from file from json.loads()",
         "processed_data": "this data may have helper keys added",
         "types": "it doesn't even need to be a dict. Whatever you want!"
      }
  

• In MatrixSections, you can now call self.units.get("some_data") to retrieve the value you returned.

Using Jinja templates

Sections can use Jinja templates to return text. Batesian will attempt to load all templates from matrix_templates/templates/. These can be accessed in Section code via template = self.env.get_template("name_of_template.tmpl"). At this point, the template is just a standard jinja2.Template. In fact, self.env is just a jinja2.Environment.

Debugging

If you don't know why your template isn't behaving as you'd expect, or you just want to add some informative logging, use self.log in either the Sections class or Units class. You'll need to add -v to build.py for these lines to show.

About

Batesian was designed to be extremely simple and just use Python as its language rather than another intermediary language like some other templating systems. This provides a lot of flexibility since you aren't contrained by a templating language. Batesian provides a thin abstraction over Jinja which is very useful when you want to do random bits of processing then dump the output into a Jinja template. Its name is derived from Batesian mimicry due to how the templating system uses Python as its language, but in a harmless way.