evariste.plugins.renderer.jinja2
¶
Abstract class for jinja2 renderers.
See also renderer.jinja2 — jinja2 renderer.
- class evariste.plugins.renderer.jinja2.Jinja2Renderer(shared: Shared)[source]¶
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 [source]¶
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] [source]¶
Iterate over subplugins of type
subtype
.This method iterates plugins (as their keywords)
{keyword}.{subtype}
, wherekeyword
is the attribute of this class, or its subclasses.For instance, given that:
the correct plugins are loaded;
plugin
renderer.html
is a subclass ofrenderer.jinja2
,
call to
Jinja2Renderer.iter_subplugins(HtmlRenderer(), "readme")
will yield:renderer.html.readme
,renderer.html.readme.mdwn
…
evariste.plugins.renderer.jinja2.file
¶
Abstract utilities for file renderers using Jinja2.
- class evariste.plugins.renderer.jinja2.file.Jinja2FileRenderer(shared)[source]¶
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()
returnsTrue
;calls
Jinja2FileRenderer.render()
, and returns its return value.
To implement such a renderer, you can:
write a
file/default
template that defines afile()
macro;set the
Jinja2FileRenderer.extension
, and write afile/default.extension
template, that defines afile()
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: Optional[str] = None¶
Extension that is automatically added at the end of the template name when searching them.
- keyword: Union[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.
- priority: int = -inf¶
When Évariste has to choose one plugin among several one, it chooses the one with higher priority.
evariste.plugins.renderer.jinja2.readme
¶
Common utilities for readme renderers using Jinja2.
- class evariste.plugins.renderer.jinja2.readme.Jinja2ReadmeRenderer(shared)[source]¶
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()
returnsTrue
);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 filefoo
isfoo.{ext}
, the README of any directory isdirectory/README.{ext}
, whereext
is one of the extensions listed here.implement
Jinja2ReadmeRenderer.render()
;
(optional) implement
Jinja2ReadmeRenderer.match()
andJinja2ReadmeRenderer.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) Optional[Tree] [source]¶
Return readme file for
tree
, orNone
if there is no such README file.
- static render(tree: Tree) str [source]¶
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.