plating 0.0.0.dev0__py3-none-any.whl

plating/template_functions.py

@@ -0,0 +1,216 @@
+#
+# plating/template_functions.py
+#
+"""Custom Jinja2 template functions for .plating rendering."""
+
+from typing import Any
+
+from jinja2 import BaseLoader, Environment, select_autoescape
+
+
+class SchemaRenderer:
+    """Renders Pyvider schemas to markdown tables."""
+
+    def render_schema(self, schema) -> str:
+        """Render schema attributes and blocks to markdown table."""
+        if not schema:
+            return "No arguments available."
+
+        markdown_parts = []
+
+        # Render main attributes
+        if hasattr(schema, "attributes") and schema.attributes:
+            markdown_parts.append(self._render_attributes_table(schema.attributes))
+
+        # Render nested blocks
+        if hasattr(schema, "blocks") and schema.blocks:
+            for block_name, block_schema in schema.blocks.items():
+                markdown_parts.append(f"\n### {block_name}\n")
+                if hasattr(block_schema, "attributes") and block_schema.attributes:
+                    markdown_parts.append(
+                        self._render_attributes_table(block_schema.attributes)
+                    )
+
+        return (
+            "\n".join(markdown_parts) if markdown_parts else "No arguments available."
+        )
+
+    def _render_attributes_table(self, attributes: dict[str, Any]) -> str:
+        """Render attributes dictionary to markdown table."""
+        if not attributes:
+            return "No arguments available."
+
+        lines = [
+            "| Argument | Type | Required | Description |",
+            "|----------|------|----------|-------------|",
+        ]
+
+        for attr_name, attr_def in attributes.items():
+            # Extract attribute properties
+            attr_type = self._format_type(getattr(attr_def, "type", "String"))
+            required = self._format_required(attr_def)
+            description = getattr(attr_def, "description", "No description available")
+
+            lines.append(
+                f"| `{attr_name}` | {attr_type} | {required} | {description} |"
+            )
+
+        return "\n".join(lines)
+
+    def _format_type(self, type_info) -> str:
+        """Format type information for display."""
+        if isinstance(type_info, str):
+            return type_info.title()
+        elif isinstance(type_info, list) and len(type_info) == 2:
+            # Handle complex types like ["list", "string"]
+            container, element = type_info
+            return f"{container.title()} of {element.title()}"
+        else:
+            return str(type_info).title()
+
+    def _format_required(self, attr_def) -> str:
+        """Format required status for display."""
+        if getattr(attr_def, "required", False):
+            return "**Yes**"
+        elif getattr(attr_def, "computed", False):
+            return "No (Computed)"
+        else:
+            return "No"
+
+
+class TemplateEngine:
+    """Jinja2 template engine with custom functions for .plating rendering."""
+
+    def __init__(self):
+        self.schema_renderer = SchemaRenderer()
+        self.env = Environment(
+            loader=BaseLoader(),
+            autoescape=select_autoescape(["html", "xml"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        # Register custom functions
+        self.env.globals.update(
+            {
+                "schema": self._schema_function,
+                "example": self._example_function,
+                "include": self._include_function,
+                "render": self._render_function,
+            }
+        )
+
+    def render_template(self, template_content: str, context: dict[str, Any]) -> str:
+        """Render template with context."""
+        # Store context for custom functions
+        self._current_context = context
+
+        try:
+            template = self.env.from_string(template_content)
+            return template.render(**context)
+        finally:
+            self._current_context = None
+
+    def _schema_function(self) -> str:
+        """{{ schema() }} - Render the component schema as markdown table."""
+        if not hasattr(self, "_current_context") or not self._current_context:
+            return "<!-- Schema not available -->"
+
+        schema = self._current_context.get("schema")
+        if not schema:
+            return "<!-- Schema not available -->"
+
+        return self.schema_renderer.render_schema(schema)
+
+    def _example_function(self, example_name: str) -> str:
+        """{{ example('name') }} - Render named example in terraform code block."""
+        if not hasattr(self, "_current_context") or not self._current_context:
+            return f"<!-- Example '{example_name}' not found -->"
+
+        examples = self._current_context.get("examples", {})
+        if example_name not in examples:
+            return f"<!-- Example '{example_name}' not found -->"
+
+        example_content = examples[example_name]
+        return f"```terraform\n{example_content}\n```"
+
+    def _include_function(self, filename: str) -> str:
+        """{{ include('filename') }} - Include static partial file."""
+        if not hasattr(self, "_current_context") or not self._current_context:
+            return f"<!-- Partial '{filename}' not found -->"
+
+        partials = self._current_context.get("partials", {})
+        if filename not in partials:
+            return f"<!-- Partial '{filename}' not found -->"
+
+        return partials[filename]
+
+    def _render_function(self, filename: str) -> str:
+        """{{ render('filename') }} - Render dynamic template partial."""
+        if not hasattr(self, "_current_context") or not self._current_context:
+            return f"<!-- Partial '{filename}' not found -->"
+
+        partials = self._current_context.get("partials", {})
+        if filename not in partials:
+            return f"<!-- Partial '{filename}' not found -->"
+
+        # Render the partial as a template with current context
+        partial_content = partials[filename]
+        try:
+            partial_template = self.env.from_string(partial_content)
+            return partial_template.render(**self._current_context)
+        except Exception as e:
+            return f"<!-- Error rendering partial '{filename}': {e} -->"
+
+
+def create_template_context(component, bundle) -> dict[str, Any]:
+    """Create template rendering context from component and bundle."""
+    context = {
+        "name": bundle.name,
+        "type": _format_component_type(bundle.component_type),
+        "examples": bundle.load_examples(),
+        "partials": bundle.load_partials(),
+    }
+
+    # Add schema if available
+    try:
+        if hasattr(component, "get_schema"):
+            context["schema"] = component.get_schema()
+        else:
+            context["schema"] = None
+    except Exception:
+        context["schema"] = None
+
+    # Add component-specific context
+    if bundle.component_type == "function":
+        context.update(_create_function_context(context["schema"]))
+
+    return context
+
+
+def _format_component_type(component_type: str) -> str:
+    """Format component type for display."""
+    type_mapping = {
+        "resource": "Resource",
+        "data_source": "Data Source",
+        "function": "Function",
+    }
+    return type_mapping.get(component_type, component_type.title())
+
+
+def _create_function_context(schema) -> dict[str, Any]:
+    """Create additional context for function components."""
+    context = {}
+
+    if schema and hasattr(schema, "parameters"):
+        # Add function-specific fields
+        context["has_parameters"] = len(schema.parameters) > 0
+        context["parameter_count"] = len(schema.parameters)
+
+        if hasattr(schema, "return_type"):
+            context["return_type"] = schema.return_type
+
+    return context
+
+
+# 🍲🥄📄🪄

plating/templates.py

@@ -0,0 +1,232 @@
+#
+# plating/templates.py
+#
+"""Template processing and rendering for documentation generation."""
+
+from typing import TYPE_CHECKING
+
+from jinja2 import DictLoader, Environment, select_autoescape
+from provide.foundation import pout
+
+if TYPE_CHECKING:
+    from .plating import PlatingBundle
+    from .generator import DocsGenerator
+
+
+class TemplateProcessor:
+    """Handles template generation and rendering."""
+
+    def __init__(self, generator: "DocsGenerator"):
+        self.generator = generator
+
+    def generate_missing_templates(self):
+        """
+        Generate missing template files - now a no-op since we use .plating bundles.
+
+        This method is kept for compatibility but .plating directories should contain
+        all necessary templates and are discovered automatically.
+        """
+        pout("📄 Using .plating bundles for templates (no template generation needed)")
+
+    def render_templates(self):
+        """Render all templates using plating bundles to generate documentation."""
+        # Ensure output directory exists
+        self.generator.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Discover all plating bundles
+        bundles = self.generator.plating_discovery.discover_bundles()
+
+        # Render provider index using built-in template
+        self._render_provider_index()
+
+        # Render each component with its plating bundle
+        for bundle in bundles:
+            self._render_component_from_bundle(bundle)
+
+    def _render_provider_index(self):
+        """Render the provider index page using built-in template."""
+        if not self.generator.provider_info:
+            return
+
+        # Built-in index template
+        index_template = """---
+page_title: "{{ provider.short_name }} Provider"
+description: |-
+  {{ provider.description }}
+---
+
+# {{ provider.rendered_name }} Provider
+
+{{ provider.description }}
+
+## Example Usage
+
+```terraform
+provider "{{ provider.short_name }}" {
+  # Configuration options
+}
+```
+
+## Schema
+
+{{ provider_schema }}
+"""
+
+        # Set up Jinja2 environment with built-in template
+        env = Environment(
+            loader=DictLoader({"index.md.tmpl": index_template}),
+            autoescape=select_autoescape(["html", "xml"]),
+        )
+
+        template = env.get_template("index.md.tmpl")
+
+        # Get provider schema if available
+        provider_schema = ""
+        if (
+            hasattr(self.generator, "schema_processor")
+            and self.generator.schema_processor
+        ):
+            try:
+                provider_schema = self.generator.schema_processor.get_provider_schema()
+                if not provider_schema:
+                    provider_schema = "No provider configuration required"
+            except Exception:
+                provider_schema = "Provider configuration documentation not available"
+        else:
+            provider_schema = "Provider configuration documentation not available"
+
+        rendered = template.render(
+            provider=self.generator.provider_info,
+            provider_schema=provider_schema,
+        )
+
+        (self.generator.output_dir / "index.md").write_text(rendered)
+
+    def _render_component_from_bundle(self, bundle: "PlatingBundle"):
+        """Render a single component using its plating bundle."""
+        # Load template and assets from bundle
+        template_content = bundle.load_main_template()
+        if not template_content:
+            pout(f"⚠️ No main template found for {bundle.name}")
+            return
+
+        examples = bundle.load_examples()
+        partials = bundle.load_partials()
+
+        # Get component info from generator
+        component_info = self._get_component_info(bundle)
+        if not component_info:
+            pout(f"⚠️ No component info found for {bundle.name}")
+            return
+
+        # Set up Jinja2 environment with custom functions
+        env = Environment(
+            loader=DictLoader(
+                {
+                    "main.tmpl.md": template_content,
+                    **partials,  # Include all partials as available templates
+                }
+            ),
+            autoescape=select_autoescape(["html", "xml"]),
+        )
+
+        # Add custom template functions
+        env.globals["schema"] = lambda: component_info.get("schema_markdown", "")
+        env.globals["example"] = (
+            lambda name: f"```terraform\n{examples.get(name, '')}\n```"
+        )
+        env.globals["include"] = lambda filename: partials.get(filename, "")
+        env.globals["render"] = lambda filename: self._render_partial(
+            env, filename, component_info, examples, partials
+        )
+
+        # Render the template
+        template = env.get_template("main.tmpl.md")
+
+        # Create render context, excluding keys that conflict with template globals
+        render_context = {
+            k: v for k, v in component_info.items() if k not in ["schema"]
+        }
+        render_context.update(
+            {
+                "bundle_name": bundle.name,
+                "bundle_type": bundle.component_type.replace("_", " ").title(),
+                "examples": examples,
+                "partials": partials,
+            }
+        )
+
+        rendered = template.render(**render_context)
+
+        # Write to output directory
+        output_dir = self.generator.output_dir / f"{bundle.component_type}s"
+        output_dir.mkdir(parents=True, exist_ok=True)
+        (output_dir / f"{bundle.name}.md").write_text(rendered)
+
+    def _render_partial(
+        self,
+        env: Environment,
+        filename: str,
+        component_info: dict,
+        examples: dict,
+        partials: dict,
+    ) -> str:
+        """Render a partial template with full context."""
+        try:
+            partial_template = env.get_template(filename)
+            return partial_template.render(
+                name=component_info.get("name", ""),
+                type=component_info.get("type", ""),
+                schema=component_info.get("schema", {}),
+                examples=examples,
+                partials=partials,
+                **component_info,
+            )
+        except Exception as e:
+            return f"<!-- Error rendering partial {filename}: {e} -->"
+
+    def _get_component_info(self, bundle: "PlatingBundle") -> dict:
+        """Get component information based on bundle type and name."""
+        # Try both the bundle name as-is and with the pyvider_ prefix
+        possible_names = [bundle.name, f"pyvider_{bundle.name}"]
+
+        if bundle.component_type == "resource":
+            for name in possible_names:
+                resource_info = self.generator.resources.get(name)
+                if resource_info:
+                    return {
+                        "name": resource_info.name,
+                        "type": resource_info.type,
+                        "description": resource_info.description,
+                        "schema": resource_info.schema,
+                        "schema_markdown": resource_info.schema_markdown,
+                    }
+        elif bundle.component_type == "data_source":
+            for name in possible_names:
+                ds_info = self.generator.data_sources.get(name)
+                if ds_info:
+                    return {
+                        "name": ds_info.name,
+                        "type": ds_info.type,
+                        "description": ds_info.description,
+                        "schema": ds_info.schema,
+                        "schema_markdown": ds_info.schema_markdown,
+                    }
+        elif bundle.component_type == "function":
+            for name in possible_names:
+                func_info = self.generator.functions.get(name)
+                if func_info:
+                    return {
+                        "name": func_info.name,
+                        "description": func_info.description,
+                        "summary": func_info.summary,
+                        "signature_markdown": func_info.signature_markdown,
+                        "arguments_markdown": func_info.arguments_markdown,
+                        "variadic_argument_markdown": func_info.variadic_argument_markdown,
+                        "has_variadic": func_info.has_variadic,
+                    }
+
+        return {}
+
+
+# 🍲🥄📄🪄