Template Customisation#

ModuleTester uses Jinja2 templates and Pandoc to generate reports in multiple formats. You can customise the appearance and content of exported documents by providing your own templates, CSS stylesheets, and reference documents.

Architecture overview#

The export pipeline works as follows:

  1. A Jinja2 template (*.j2) is rendered to an intermediate HTML string.

  2. Pandoc converts the HTML to the target format (DOCX, ODT, PDF, etc.).

  3. For HTML output, a CSS stylesheet is embedded directly in the file.

  4. For DOCX/ODT output, a reference document controls styles and formatting.

The export engine is implemented in moduletester.new_exporter and uses a FileSystemLoader pointed at the template_dir directory configured in moduletester.ini.

Default templates#

ModuleTester ships with the following files in its default_templates/ directory:

File

Purpose

test_results_template.j2

Main report template. Renders test descriptions, commands, results, and status icons grouped by sub-module.

test_list_template.j2

Simplified template that lists tests without detailed results.

default_style.css

CSS stylesheet embedded in HTML exports. Controls layout, code block styling, and result formatting.

custom-reference.docx

Word reference document used by Pandoc. Defines heading styles, fonts, and page layout for DOCX exports.

custom-reference.odt

LibreOffice reference document used by Pandoc. Same role as the DOCX reference for ODT exports.

Using custom templates#

To override the default templates:

  1. Create a directory in your package (e.g. my_templates/).

  2. Copy the default templates you want to modify into that directory.

  3. Set template_dir in your moduletester.ini:

    [export]
template_dir = my_templates

    The path is relative to the package root directory.

  4. Edit the copied templates as needed.

Tip

Set reload_templates_on_export = 1 in moduletester.ini while developing templates. This forces ModuleTester to reload templates from disk on every export, so you can iterate without restarting the application.

Template variables#

Inside a Jinja2 template, the main context object is doc_obj, an instance of DocumentExporter. The most useful attributes are:

Variable

Description

doc_obj.test_suite

The TestSuite object containing all tests and results.

doc_obj.test_suite.package

The Module object for the loaded package (name, path, etc.).

doc_obj.test_suite.package.full_name

Fully qualified package name (e.g. guidata).

doc_obj.test_suite.author

Author string (or None).

doc_obj.test_suite.last_run

Date/time of the last test execution.

doc_obj.test_suite.tests

List of all Test objects.

doc_obj.test_suite.group_tests()

Returns a dict grouping tests by sub-module name.

doc_obj.docstrings_header_shift

Heading level shift for embedded docstrings.

doc_obj.toc_depth

Table of contents depth.

Each Test object provides:

Attribute

Description

test.package.last_name

Test script filename (without path).

test.command

The command line used to execute the test.

test.result

The TestResult object (or None if not yet run).

test.result.result_name

Human-readable result string (e.g. “Accepted”, “Failed”).

test.result.result.icon_path

Path to the status icon image.

test.result.last_run

Date/time of this test’s last run.

test.get_html_description(...)

Renders the test docstring as HTML.

The translation function _() is available globally in templates for internationalised strings.

CSS customisation#

The default_style.css file controls the appearance of HTML exports. You can override it by placing your own CSS file in your custom template directory and setting the css_style option:

[export]
css_style = my_style.css

The CSS is embedded directly in the HTML output using Pandoc’s --embed-resources flag.

DOCX and ODT reference documents#

Pandoc uses reference documents to control styles in Word and LibreOffice exports. To customise:

  1. Open the default reference document (custom-reference.docx or custom-reference.odt) in your word processor.

  2. Modify the styles (headings, body text, fonts, margins, etc.) without changing the content structure.

  3. Save the modified file in your custom template directory and update moduletester.ini:

    [export]
docx_reference = my-reference.docx
odt_reference = my-reference.odt

See the Pandoc documentation on reference documents for details on which styles are used.