renderer Rust

Tera-based documentation renderer

This module provides the Renderer struct which combines Tera templating with theme adapters to generate styled documentation output.

Structs

struct Renderer

pub

Documentation renderer using Tera templates with SSG-native theming.

The Renderer holds a Tera instance with pre-loaded templates and a theme adapter for CSS variable injection. Templates access theme values through the theme context variable.

Examples:

use plissken_core::render::Renderer;

// Without user overrides
let renderer = Renderer::new(Some("mkdocs-material"), None).unwrap();
let output = renderer.badge_async().unwrap();
assert!(output.contains("var(--md-"));

// With user overrides from project root
use std::path::Path;
let renderer = Renderer::new(Some("mkdocs-material"), Some(Path::new("."))).unwrap();

Fields

Name	Type	Description
tera	Tera
theme	Box < dyn ThemeAdapter >
template_loader	TemplateLoader

Methods

new pub

fn new (template : Option < & str > , project_root : Option < & Path >) -> crate :: error :: Result < Self >

Create a new renderer with the specified template theme.

Parameters:

Name	Type	Description
template	-	Optional template name (e.g., "mkdocs-material", "mdbook")
project_root	-	Optional project root for user template overrides. If provided, templates in .plissken/templates/ will override defaults.

Raises:

Exception	Description
Error	Returns PlisskenError::Template if template initialization fails.

Source

    pub fn new(template: Option<&str>, project_root: Option<&Path>) -> crate::error::Result<Self> {
        let template_loader = TemplateLoader::new(project_root);
        let mut tera = Tera::default();

        // Load templates from the template loader (supports user overrides)
        tera.add_raw_templates(vec![
            ("partials/badge.html", template_loader.get("partials/badge.html")?),
            ("partials/code_block.html", template_loader.get("partials/code_block.html")?),
            ("partials/signature.html", template_loader.get("partials/signature.html")?),
            ("module.html", template_loader.get("module.html")?),
        ])?;

        let theme = get_theme_adapter(template);

        Ok(Self { tera, theme, template_loader })
    }

has_user_override pub

fn has_user_override (& self , template_name : & str) -> bool

Check if a user override exists for the given template.

Source

    pub fn has_user_override(&self, template_name: &str) -> bool {
        self.template_loader.has_user_override(template_name)
    }

template_loader pub

fn template_loader (& self) -> & TemplateLoader

Get the template loader for direct access to templates.

Source

    pub fn template_loader(&self) -> &TemplateLoader {
        &self.template_loader
    }

theme_name pub

fn theme_name (& self) -> & str

Get the theme adapter name.

Source

    pub fn theme_name(&self) -> &str {
        self.theme.name()
    }

base_context pub

fn base_context (& self) -> Context

Create a base Tera context with theme values injected.

This context includes the theme object with all CSS variable mappings, ready for use in templates.

Source

    pub fn base_context(&self) -> Context {
        let mut ctx = Context::new();

        // Inject theme values as a nested object
        ctx.insert(
            "theme",
            &ThemeContext {
                // Core colors
                code_bg: self.theme.code_bg().to_string(),
                code_fg: self.theme.code_fg().to_string(),
                primary: self.theme.primary().to_string(),
                accent: self.theme.accent().to_string(),
                muted: self.theme.muted().to_string(),
                border: self.theme.border().to_string(),
                name: self.theme.name().to_string(),
                // Semantic colors
                success: self.theme.success().to_string(),
                warning: self.theme.warning().to_string(),
                error: self.theme.error().to_string(),
                info: self.theme.info().to_string(),
                // Badge colors
                badge_async: self.theme.badge_async().to_string(),
                badge_unsafe: self.theme.badge_unsafe().to_string(),
                badge_deprecated: self.theme.badge_deprecated().to_string(),
                badge_binding: self.theme.badge_binding().to_string(),
                badge_pub: self.theme.badge_pub().to_string(),
                badge_pub_crate: self.theme.badge_pub_crate().to_string(),
                badge_rust: self.theme.badge_rust().to_string(),
                badge_python: self.theme.badge_python().to_string(),
            },
        );

        ctx
    }

render_badge pub

fn render_badge (& self , text : & str , color_type : & str , badge_type : & str ,) -> Result < String , tera :: Error >

Render a badge with the given text, color type, and semantic type.

Parameters:

Name	Type	Description
text	-	The badge text (e.g., "async", "deprecated")
color_type	-	Color type: "blue", "green", "yellow", "red", "purple", "orange", "gray"
badge_type	-	Semantic type for CSS class (e.g., "async", "visibility", "source")

Source

    pub fn render_badge(
        &self,
        text: &str,
        color_type: &str,
        badge_type: &str,
    ) -> Result<String, tera::Error> {
        let mut ctx = self.base_context();
        ctx.insert("text", text);
        ctx.insert("color_type", color_type);
        ctx.insert("badge_type", badge_type);
        self.tera.render("partials/badge.html", &ctx)
    }

badge_async pub

fn badge_async (& self) -> Result < String , tera :: Error >

Render an "async" badge (blue).

Source

    pub fn badge_async(&self) -> Result<String, tera::Error> {
        self.render_badge("async", "blue", "async")
    }

badge_unsafe pub

fn badge_unsafe (& self) -> Result < String , tera :: Error >

Render an "unsafe" badge (red).

Source

    pub fn badge_unsafe(&self) -> Result<String, tera::Error> {
        self.render_badge("unsafe", "red", "unsafe")
    }

badge_deprecated pub

fn badge_deprecated (& self) -> Result < String , tera :: Error >

Render a "deprecated" badge (yellow).

Source

    pub fn badge_deprecated(&self) -> Result<String, tera::Error> {
        self.render_badge("deprecated", "yellow", "deprecated")
    }

badge_visibility pub

fn badge_visibility (& self , visibility : & str) -> Result < String , tera :: Error >

Render a visibility badge.

Parameters:

Name	Type	Description
visibility	-	One of: "pub", "pub(crate)", "private"

Source

    pub fn badge_visibility(&self, visibility: &str) -> Result<String, tera::Error> {
        let color = match visibility {
            "pub" => "green",
            "pub(crate)" => "orange",
            _ => "gray", // private
        };
        self.render_badge(visibility, color, "visibility")
    }

badge_source pub

fn badge_source (& self , source_type : & str) -> Result < String , tera :: Error >

Render a source type badge with emoji.

Parameters:

Name	Type	Description
source_type	-	One of: "python", "rust", "binding"

Source

    pub fn badge_source(&self, source_type: &str) -> Result<String, tera::Error> {
        let (text, color) = match source_type.to_lowercase().as_str() {
            "python" => ("Python", "blue"),
            "rust" => ("Rust", "orange"),
            "binding" | "pyo3" => ("Binding", "purple"),
            _ => (source_type, "gray"),
        };
        self.render_badge(text, color, "source")
    }

render_code_block pub

fn render_code_block (& self , code : & str , language : Option < & str > , caption : Option < & str > ,) -> Result < String , tera :: Error >

Render a code block with optional language and caption.

Parameters:

Name	Type	Description
code	-	The code content
language	-	Optional language for syntax highlighting
caption	-	Optional caption/title for the code block

Source

    pub fn render_code_block(
        &self,
        code: &str,
        language: Option<&str>,
        caption: Option<&str>,
    ) -> Result<String, tera::Error> {
        let mut ctx = self.base_context();
        ctx.insert("code", code);
        ctx.insert("language", &language.unwrap_or(""));
        ctx.insert("caption", &caption.unwrap_or(""));
        self.tera.render("partials/code_block.html", &ctx)
    }

render_signature pub

fn render_signature (& self , name : & str , params : & str , return_type : Option < & str > , is_async : bool ,) -> Result < String , tera :: Error >

Render a function/method signature.

Parameters:

Name	Type	Description
name	-	Function name
params	-	Parameter list as a string
return_type	-	Optional return type
is_async	-	Whether the function is async

Source

    pub fn render_signature(
        &self,
        name: &str,
        params: &str,
        return_type: Option<&str>,
        is_async: bool,
    ) -> Result<String, tera::Error> {
        let mut ctx = self.base_context();
        ctx.insert("name", name);
        ctx.insert("params", params);
        ctx.insert("return_type", &return_type.unwrap_or(""));
        ctx.insert("is_async", &is_async);
        self.tera.render("partials/signature.html", &ctx)
    }

render_module pub

fn render_module (& self , module_name : & str , description : & str , functions : & [String] , classes : & [String] ,) -> Result < String , tera :: Error >

Render a module documentation page.

Parameters:

Name	Type	Description
module_name	-	Name of the module
description	-	Module description/docstring
functions	-	List of function documentation sections
classes	-	List of class documentation sections

Source

    pub fn render_module(
        &self,
        module_name: &str,
        description: &str,
        functions: &[String],
        classes: &[String],
    ) -> Result<String, tera::Error> {
        let mut ctx = self.base_context();
        ctx.insert("module_name", module_name);
        ctx.insert("description", description);
        ctx.insert("functions", functions);
        ctx.insert("classes", classes);
        self.tera.render("module.html", &ctx)
    }

render_template pub

fn render_template (& self , template_name : & str , extra_context : & Context ,) -> Result < String , tera :: Error >

Render an arbitrary template with the given context.

The theme values are automatically injected into the context.

Source

    pub fn render_template(
        &self,
        template_name: &str,
        extra_context: &Context,
    ) -> Result<String, tera::Error> {
        let mut ctx = self.base_context();
        // Merge extra context (extra context values override base if there are conflicts)
        let json_value = extra_context.clone().into_json();
        let obj = json_value
            .as_object()
            .ok_or_else(|| tera::Error::msg("extra_context must serialize to a JSON object"))?;
        for (key, value) in obj {
            ctx.insert(key, value);
        }
        self.tera.render(template_name, &ctx)
    }

struct ThemeContext

private

Derives: serde :: Serialize

Theme context for Tera templates.

This struct is serialized into the Tera context as the theme variable, allowing templates to access theme values like {{ theme.code_bg }}.

Fields

Name	Type	Description
code_bg	String
code_fg	String
primary	String
accent	String
muted	String
border	String
name	String
success	String
warning	String
error	String
info	String
badge_async	String
badge_unsafe	String
badge_deprecated	String
badge_binding	String
badge_pub	String
badge_pub_crate	String
badge_rust	String
badge_python	String