evariste.plugins.renderer.jinja2

Abstract class for jinja2 renderers.

See also renderer.jinja2 — jinja2 renderer.

class evariste.plugins.renderer.jinja2.Jinja2Renderer(shared: Shared)

Abstract class for jinja2 renderers.

To write your own renderer:

• subclass this class;

• define a default template name: Jinja2Renderer.template;

• write such a template file, and place it in one of the templatedirs. The following template variables are defined and can be used in the template: Template;

• you can also overwrite the methods defined here.

You might also have a look at the implementation of the HTML renderer.

• Each file can be rendered in its own way: see Jinja2FileRenderer (for instance, you might want to add a nice thumbnail to files that are images);

• To define how files are annotated, see Jinja2ReadmeRenderer.

default_setup: dict[str, str] = {'destfile': 'output'}

Default value for section self.keyword in the setup file. It may be overwritten by data provided by user in the setup file. See Plugin.default_setup and Plugin.global_default_setup.

get_readme(tree: Tree) → Tree

Iterate the only README file for tree.

If there is such a README file, iterate over it (a single value); otherwise, iterate nothing.

Side effect: Store a (partial) function in self.readmes[tree.from_source] to render this README file.

iter_subplugins(subtype: str) → Iterable[Plugin]

Iterate over subplugins of type subtype.

This method iterates plugins (as their keywords) {keyword}.{subtype}, where keyword is the attribute of this class, or its subclasses.

For instance, given that:

• the correct plugins are loaded;

• plugin renderer.html is a subclass of renderer.jinja2,

call to Jinja2Renderer.iter_subplugins(HtmlRenderer(), "readme") will yield: renderer.html.readme, renderer.html.readme.markdown…

render(builder: Builder) → None

Render the tree as a file, and write result into the destination file.

render_tree(tree: Tree) → str

Render the tree using templates, and return the string.

template: str = None

Name of the default template.

evariste.plugins.renderer.jinja2.file

Abstract utilities for file renderers using Jinja2.

class evariste.plugins.renderer.jinja2.file.Jinja2FileRenderer(shared)

Renderer of file using jinja2.

This is an abstract class that defines a default renderer for files.

From within a template, the macro render_file can be called, which:

• looks for the first plugin that matches this file (that is, the first plugin where Jinja2FileRenderer.match() returns True;

• calls Jinja2FileRenderer.render(), and returns its return value.

To implement such a renderer, you can:

• write a file/default template that defines a file() macro;

• set the Jinja2FileRenderer.extension, and write a file/default.extension template, that defines a file() macro;

• overwrite the Jinja2FileRenderer.render() method, if the default implementation does not pleas you.

You can also overwrite Jinja2FileRenderer.match(), so that your subplugin cannot be applied to any file, but only to some of them.

extension: str | None = None

Extension that is automatically added at the end of the template name when searching them.

keyword: None | str = None

Keyword plugin, used to reference it: it is used to enable plugins in the setup file, to name its section in the setup file, etc.

match(filename: Tree) → bool

This is the default renderer, that matches everything.

priority: int = -inf

When Évariste has to choose one plugin among several one, it chooses the one with higher priority.

render(filename: Tree, context: jinja2.runtime.Context) → str

Render tree, which is a File

By default, call the file() macro, with filename as argument, and returns its value.

template: str = 'default'

Name of the template rendering files.

evariste.plugins.renderer.jinja2.readme

Common utilities for readme renderers using Jinja2.

class evariste.plugins.renderer.jinja2.readme.Jinja2ReadmeRenderer(shared)

Default readme renderer using jinja2.

This is an abstract class that defines a default README renderer for files. From within a template, the macro render_readme can be called to annotate a file, which:

• looks for the first plugin that matches this file (that is, the first plugin where Jinja2ReadmeRenderer.match() returns True);

• calls Jinja2ReadmeRenderer.render(), and returns its return value.

To implement such a renderer, in a subclass:

• do one of:

  • set Jinja2ReadmeRenderer.extensions as a list of extensions: the README of any file foo is foo.{ext}, the README of any directory is directory/README.{ext}, where ext is one of the extensions listed here.

  • implement Jinja2ReadmeRenderer.render();

• (optional) implement Jinja2ReadmeRenderer.match() and Jinja2ReadmeRenderer.get_readme() if the default implementation does not please you.

extensions: list[str] = []

List of extensions of the READMEs (see Jinja2ReadmeRenderer).

get_readme(tree: Tree) → Tree | None

Return readme file for tree, or None if there is no such README file.

match(tree: Tree) → bool

Return True if this plugin can handle the README of the argument.

static render(tree: Tree) → str

Render argument as README.

Return a string to be included when rendering the template. The functions and variables available in the template are described in renderer.jinja2 — jinja2 renderer.