plating 0.0.0.dev0__py3-none-any.whl

plating/__init__.py

@@ -0,0 +1,27 @@
+#
+# plating/__init__.py
+#
+"""Garnish - Documentation generation for Terraform/OpenTofu providers.
+
+This package implements a comprehensive documentation generation system modeled after
+HashiCorp's tfplugindocs tool. It extracts provider schemas, processes templates and
+examples, and generates Terraform Registry-compliant documentation.
+"""
+
+from plating._version import __version__
+
+from plating.cli import main
+from plating.generator import DocsGenerator
+from plating.models import FunctionInfo, ProviderInfo, ResourceInfo
+
+__all__ = [
+    "__version__",
+    "DocsGenerator",
+    "FunctionInfo",
+    "ProviderInfo",
+    "ResourceInfo",
+    "main",
+]
+
+
+# 🥄📚🪄

plating/_version.py

@@ -0,0 +1,53 @@
+#
+# _version.py
+#
+"""
+Version handling for plating.
+Uses VERSION file with robust fallback mechanisms.
+"""
+
+from pathlib import Path
+
+
+def _find_project_root() -> Path | None:
+    """Find the project root directory by looking for VERSION file."""
+    current = Path(__file__).parent
+    
+    # Walk up the directory tree looking for VERSION file
+    while current != current.parent:  # Stop at filesystem root
+        version_file = current / "VERSION"
+        if version_file.exists():
+            return current
+        current = current.parent
+    
+    return None
+
+
+def get_version() -> str:
+    """Get the current garnish version.
+
+    Reads from VERSION file if it exists, otherwise falls back to package metadata,
+    then to default development version.
+    
+    Returns:
+        str: The current version string
+    """
+    # Try VERSION file first (single source of truth)
+    project_root = _find_project_root()
+    if project_root:
+        version_file = project_root / "VERSION"
+        if version_file.exists():
+            return version_file.read_text().strip()
+    
+    # Fallback to package metadata
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        return version("plating")
+    except PackageNotFoundError:
+        pass
+    
+    # Final fallback
+    return "0.0.0-dev"
+
+
+__version__ = get_version()

plating/adorner/__init__.py

@@ -0,0 +1,16 @@
+#
+# plating/adorner/__init__.py
+#
+"""Adorning system for adding .plating directories to components."""
+
+from plating.adorner.api import adorn_components, adorn_missing_components
+from plating.adorner.adorner import PlatingAdorner
+
+__all__ = [
+    "PlatingAdorner",
+    "adorn_components",
+    "adorn_missing_components",
+]
+
+
+# 🍲🥄👗🪄

plating/adorner/adorner.py

@@ -0,0 +1,115 @@
+#
+# plating/adorner/adorner.py
+#
+"""Core adorner implementation."""
+
+import asyncio
+
+from pyvider.hub import ComponentDiscovery, hub
+from provide.foundation import logger, pout, perr
+
+from plating.adorner.finder import ComponentFinder
+from plating.adorner.templates import TemplateGenerator
+from plating.errors import AdorningError, handle_error
+from plating.plating import PlatingDiscovery
+
+
+class PlatingAdorner:
+    """Adorns components with .plating directories."""
+
+    def __init__(self):
+        self.plating_discovery = PlatingDiscovery()
+        self.template_generator = TemplateGenerator()
+        self.component_finder = ComponentFinder()
+
+    async def adorn_missing(self, component_types: list[str] = None) -> dict[str, int]:
+        """
+        Adorn components with missing .plating directories.
+
+        Returns a dictionary with counts of adorned components by type.
+        """
+        # Discover all components via hub
+        discovery = ComponentDiscovery(hub)
+        await discovery.discover_all()
+        components = hub.list_components()
+
+        # Find existing plating bundles
+        existing_bundles = await asyncio.to_thread(
+            self.plating_discovery.discover_bundles
+        )
+        existing_names = {bundle.name for bundle in existing_bundles}
+
+        # Track adorning results
+        adorned = {"resource": 0, "data_source": 0, "function": 0}
+
+        # Filter by component types if specified
+        target_types = component_types or ["resource", "data_source", "function"]
+
+        # Adorn missing components
+        for component_type in target_types:
+            if component_type in components:
+                for name, component_class in components[component_type].items():
+                    if name not in existing_names:
+                        success = await self._adorn_component(
+                            name, component_type, component_class
+                        )
+                        if success:
+                            adorned[component_type] += 1
+
+        return adorned
+
+    async def _adorn_component(
+        self, name: str, component_type: str, component_class
+    ) -> bool:
+        """Adorn a single component with a .plating directory."""
+        try:
+            # Find the component's source file location
+            logger.trace(f"Looking for source file for {name}")
+            source_file = await self.component_finder.find_source(component_class)
+            if not source_file:
+                logger.warning(f"Could not find source file for {name}")
+                pout(f"⚠️ Could not find source file for {name}")
+                return False
+
+            # Create .plating directory structure
+            plating_dir = source_file.parent / f"{source_file.stem}.plating"
+            docs_dir = plating_dir / "docs"
+            examples_dir = plating_dir / "examples"
+
+            logger.trace(f"Creating .plating directory at {plating_dir}")
+            try:
+                await asyncio.to_thread(docs_dir.mkdir, parents=True, exist_ok=True)
+                await asyncio.to_thread(examples_dir.mkdir, parents=True, exist_ok=True)
+            except OSError as e:
+                raise AdorningError(
+                    name, component_type, f"Failed to create directories: {e}"
+                )
+
+            # Generate and write template
+            template_content = await self.template_generator.generate_template(
+                name, component_type, component_class
+            )
+            template_file = docs_dir / f"{name}.tmpl.md"
+            await asyncio.to_thread(template_file.write_text, template_content)
+
+            # Generate and write example
+            example_content = await self.template_generator.generate_example(
+                name, component_type
+            )
+            example_file = examples_dir / "example.tf"
+            await asyncio.to_thread(example_file.write_text, example_content)
+
+            logger.info(f"Successfully adorned {component_type}: {name}")
+            pout(f"✅ Adorned {component_type}: {name}")
+            return True
+
+        except AdorningError:
+            raise  # Re-raise our custom errors
+        except Exception as e:
+            error = AdorningError(name, component_type, str(e))
+            handle_error(error, logger)
+            perr(f"❌ Failed to adorn {name}: {e}")
+            return False
+
+
+# 🍲🥄👗🪄

plating/adorner/api.py

@@ -0,0 +1,24 @@
+#
+# plating/adorner/api.py
+#
+"""Public API for the adorner module."""
+
+import asyncio
+
+from plating.adorner.adorner import PlatingAdorner
+
+
+# Async entry point
+async def adorn_missing_components(component_types: list[str] = None) -> dict[str, int]:
+    """Adorn components with missing .plating directories."""
+    adorner = PlatingAdorner()
+    return await adorner.adorn_missing(component_types)
+
+
+# Sync entry point
+def adorn_components(component_types: list[str] = None) -> dict[str, int]:
+    """Sync entry point for adorning components."""
+    return asyncio.run(adorn_missing_components(component_types))
+
+
+# 🍲🥄👗🎯🪄

plating/adorner/finder.py

@@ -0,0 +1,22 @@
+#
+# plating/adorner/finder.py
+#
+"""Component source file finding utilities."""
+
+import inspect
+from pathlib import Path
+
+
+class ComponentFinder:
+    """Finds source files for components."""
+
+    async def find_source(self, component_class) -> Path | None:
+        """Find the source file for a component class."""
+        try:
+            source_file = inspect.getfile(component_class)
+            return Path(source_file)
+        except Exception:
+            return None
+
+
+# 🍲🥄🔍🪄

plating/adorner/templates.py

@@ -0,0 +1,199 @@
+#
+# plating/adorner/templates.py
+#
+"""Template generation for adorned components."""
+
+
+class TemplateGenerator:
+    """Generates templates and examples for components."""
+
+    async def generate_template(
+        self, name: str, component_type: str, component_class
+    ) -> str:
+        """Generate template content based on component type."""
+        # Get component description if available
+        try:
+            doc = component_class.__doc__
+            # Check if it's a real docstring (not from Mock or other test objects)
+            if doc:
+                doc_stripped = doc.strip()
+                if not doc_stripped.startswith("Create a new `Mock`"):
+                    description = doc_stripped.split("\n")[0]  # First line only
+                else:
+                    description = (
+                        f"Terraform {component_type.replace('_', ' ')} for {name}"
+                    )
+            else:
+                description = f"Terraform {component_type.replace('_', ' ')} for {name}"
+        except AttributeError:
+            # No docstring attribute
+            description = f"Terraform {component_type.replace('_', ' ')} for {name}"
+
+        if component_type == "resource":
+            return self._resource_template(name, description)
+        elif component_type == "data_source":
+            return self._data_source_template(name, description)
+        elif component_type == "function":
+            return self._function_template(name, description)
+        else:
+            return self._generic_template(name, description, component_type)
+
+    async def generate_example(self, name: str, component_type: str) -> str:
+        """Generate example Terraform content."""
+        if component_type == "resource":
+            return self._resource_example(name)
+        elif component_type == "data_source":
+            return self._data_source_example(name)
+        elif component_type == "function":
+            return self._function_example(name)
+        else:
+            return self._generic_example(name)
+
+    def _resource_template(self, name: str, description: str) -> str:
+        """Generate resource template content."""
+        return f"""---
+page_title: "Resource: {name}"
+description: |-
+  {description}
+---
+
+# {name} (Resource)
+
+{description}
+
+## Example Usage
+
+{{{{ example("example") }}}}
+
+## Argument Reference
+
+{{{{ schema() }}}}
+
+## Import
+
+```bash
+terraform import {name}.example <id>
+```
+"""
+
+    def _data_source_template(self, name: str, description: str) -> str:
+        """Generate data source template content."""
+        return f"""---
+page_title: "Data Source: {name}"
+description: |-
+  {description}
+---
+
+# {name} (Data Source)
+
+{description}
+
+## Example Usage
+
+{{{{ example("example") }}}}
+
+## Argument Reference
+
+{{{{ schema() }}}}
+"""
+
+    def _function_template(self, name: str, description: str) -> str:
+        """Generate function template content."""
+        return f"""---
+page_title: "Function: {name}"
+description: |-
+  {description}
+---
+
+# {name} (Function)
+
+{description}
+
+## Example Usage
+
+{{{{ example("example") }}}}
+
+## Signature
+
+`{{{{ signature_markdown }}}}`
+
+## Arguments
+
+{{{{ arguments_markdown }}}}
+
+{{% if has_variadic %}}
+## Variadic Arguments
+
+{{{{ variadic_argument_markdown }}}}
+{{% endif %}}
+"""
+
+    def _generic_template(
+        self, name: str, description: str, component_type: str
+    ) -> str:
+        """Generate generic template content."""
+        return f"""---
+page_title: "{component_type.title()}: {name}"
+description: |-
+  {description}
+---
+
+# {name} ({component_type.title()})
+
+{description}
+
+## Example Usage
+
+{{{{ example("example") }}}}
+
+## Schema
+
+{{{{ schema() }}}}
+"""
+
+    def _resource_example(self, name: str) -> str:
+        """Generate resource example."""
+        return f'''resource "{name}" "example" {{
+  # Configuration options here
+}}
+
+output "example_id" {{
+  description = "The ID of the {name} resource"
+  value       = {name}.example.id
+}}
+'''
+
+    def _data_source_example(self, name: str) -> str:
+        """Generate data source example."""
+        return f'''data "{name}" "example" {{
+  # Configuration options here
+}}
+
+output "example_data" {{
+  description = "Data from {name}"
+  value       = data.{name}.example
+}}
+'''
+
+    def _function_example(self, name: str) -> str:
+        """Generate function example."""
+        return f"""locals {{
+  example_result = {name}(
+    # Function arguments here
+  )
+}}
+
+output "function_result" {{
+  description = "Result of {name} function"  
+  value       = local.example_result
+}}
+"""
+
+    def _generic_example(self, name: str) -> str:
+        """Generate generic example."""
+        return f"""# Example usage for {name}
+# Add your Terraform configuration here
+"""
+
+
+# 🍲🥄👗📝🪄