plating 0.0.0.dev0__py3-none-any.whl

plating/generator.py

@@ -0,0 +1,192 @@
+#
+# plating/generator.py
+#
+"""Main documentation generator class and entry point."""
+
+from pathlib import Path
+
+from provide.foundation import pout
+
+from plating.plating import PlatingDiscovery
+from plating.models import FunctionInfo, ProviderInfo, ResourceInfo
+from plating.schema import SchemaProcessor
+from plating.templates import TemplateProcessor
+
+
+class DocsGenerator:
+    """Main documentation generator class."""
+
+    def __init__(
+        self,
+        provider_dir: Path,
+        provider_name: str | None = None,
+        rendered_provider_name: str | None = None,
+        examples_dir: str = "examples",
+        templates_dir: str = "templates",
+        output_dir: str = "docs",
+        ignore_deprecated: bool = False,
+    ):
+        self.provider_dir = Path(provider_dir).resolve()
+        self.examples_dir = self.provider_dir / examples_dir
+        self.templates_dir = self.provider_dir / templates_dir
+        self.output_dir = self.provider_dir / output_dir
+        self.ignore_deprecated = ignore_deprecated
+
+        # Determine provider name
+        if provider_name:
+            self.provider_name = provider_name
+        else:
+            # Extract from directory name, removing terraform-provider- prefix
+            dir_name = self.provider_dir.name
+            if dir_name.startswith("terraform-provider-"):
+                self.provider_name = dir_name[19:]  # Remove "terraform-provider-"
+            else:
+                self.provider_name = dir_name
+
+        self.rendered_provider_name = rendered_provider_name or self.provider_name
+
+        # Internal state
+        self.provider_schema = None
+        self.provider_info: ProviderInfo | None = None
+        self.resources: dict[str, ResourceInfo] = {}
+        self.data_sources: dict[str, ResourceInfo] = {}
+        self.functions: dict[str, FunctionInfo] = {}
+
+        # Initialize processors
+        self.schema_processor = SchemaProcessor(self)
+        self.template_processor = TemplateProcessor(self)
+        self.plating_discovery = PlatingDiscovery()
+
+    def process_examples(self):
+        """Process example files and associate them with resources/data sources."""
+        if not self.examples_dir.exists():
+            return
+
+        # Process provider examples
+        provider_example = None
+        if (self.examples_dir / "provider" / "provider.tf").exists():
+            provider_example = (
+                self.examples_dir / "provider" / "provider.tf"
+            ).read_text()
+        elif (self.examples_dir / "provider.tf").exists():
+            provider_example = (self.examples_dir / "provider.tf").read_text()
+
+        if provider_example and self.provider_info:
+            self.provider_info.has_example = True
+            self.provider_info.example_file = provider_example
+
+        # Process resource examples
+        for resource_name, resource_info in self.resources.items():
+            example_patterns = [
+                self.examples_dir / "resources" / f"{resource_name}" / "resource.tf",
+                self.examples_dir / "resources" / f"{resource_name}.tf",
+                self.examples_dir / f"{resource_name}.tf",
+            ]
+
+            for pattern in example_patterns:
+                if pattern.exists():
+                    resource_info.has_example = True
+                    resource_info.example_file = pattern.read_text()
+                    break
+
+            # Process import examples
+            import_patterns = [
+                self.examples_dir / "resources" / f"{resource_name}" / "import.sh",
+                self.examples_dir / "resources" / f"{resource_name}_import.sh",
+                self.examples_dir / f"{resource_name}_import.sh",
+            ]
+
+            for pattern in import_patterns:
+                if pattern.exists():
+                    resource_info.has_import = True
+                    resource_info.import_file = pattern.read_text()
+                    break
+
+        # Process data source examples
+        for ds_name, ds_info in self.data_sources.items():
+            example_patterns = [
+                self.examples_dir / "data-sources" / f"{ds_name}" / "data-source.tf",
+                self.examples_dir / "data-sources" / f"{ds_name}.tf",
+                self.examples_dir / f"{ds_name}.tf",
+            ]
+
+            for pattern in example_patterns:
+                if pattern.exists():
+                    ds_info.has_example = True
+                    ds_info.example_file = pattern.read_text()
+                    break
+
+        # Process function examples
+        for func_name, func_info in self.functions.items():
+            example_patterns = [
+                self.examples_dir / "functions" / f"{func_name}" / "function.tf",
+                self.examples_dir / "functions" / f"{func_name}.tf",
+                self.examples_dir / f"{func_name}.tf",
+            ]
+
+            for pattern in example_patterns:
+                if pattern.exists():
+                    func_info.has_example = True
+                    func_info.example_file = pattern.read_text()
+                    break
+
+    def generate(self):
+        """Generate documentation for the provider."""
+        pout(f"🔍 Generating documentation for {self.provider_name} provider...")
+
+        # Extract provider schema
+        pout("📋 Extracting provider schema...")
+        self.provider_schema = self.schema_processor.extract_provider_schema()
+
+        # Parse schema into our internal structures
+        self.schema_processor.parse_provider_schema()
+
+        # Process examples
+        pout("📁 Processing examples...")
+        self.process_examples()
+
+        # Generate missing templates
+        pout("📄 Generating missing templates...")
+        self.template_processor.generate_missing_templates()
+
+        # Render templates
+        pout("🎨 Rendering templates...")
+        self.template_processor.render_templates()
+
+        pout(f"✅ Documentation generated successfully in {self.output_dir}")
+
+
+def generate_docs(
+    provider_dir: Path = Path(),
+    provider_name: str | None = None,
+    rendered_provider_name: str | None = None,
+    examples_dir: str = "examples",
+    templates_dir: str = "templates",
+    output_dir: str = "docs",
+    ignore_deprecated: bool = False,
+) -> None:
+    """Generate documentation for a Pyvider provider.
+
+    Args:
+        provider_dir: Path to the provider directory
+        provider_name: Name of the provider (auto-detected if None)
+        rendered_provider_name: Display name for the provider
+        examples_dir: Directory containing example files
+        templates_dir: Directory containing template files
+        output_dir: Directory to output generated documentation
+        ignore_deprecated: Whether to skip deprecated resources
+    """
+    generator = DocsGenerator(
+        provider_dir=provider_dir,
+        provider_name=provider_name,
+        rendered_provider_name=rendered_provider_name,
+        examples_dir=examples_dir,
+        templates_dir=templates_dir,
+        output_dir=output_dir,
+        ignore_deprecated=ignore_deprecated,
+    )
+
+    generator.generate()
+
+
+# 🍲🥄📄🪄

plating/linting.py

@@ -0,0 +1,235 @@
+#
+# plating/linting.py
+#
+"""Markdown linting integration for documentation generation."""
+
+import json
+from pathlib import Path
+import subprocess
+
+
+class MarkdownLinter:
+    """Handles markdown linting for generated documentation."""
+
+    def __init__(self, config_file: Path | None = None):
+        self.config_file = config_file
+
+    def lint_templates(self, template_dir: Path) -> tuple[bool, list[dict]]:
+        """Lint template files before generation.
+
+        Args:
+            template_dir: Directory containing template files
+
+        Returns:
+            Tuple of (success, errors) where errors is a list of error dictionaries
+        """
+        return self._run_markdownlint(f"{template_dir}/**/*.tmpl.md")
+
+    def lint_generated_docs(self, output_dir: Path) -> tuple[bool, list[dict]]:
+        """Lint generated documentation files.
+
+        Args:
+            output_dir: Directory containing generated markdown files
+
+        Returns:
+            Tuple of (success, errors) where errors is a list of error dictionaries
+        """
+        return self._run_markdownlint(f"{output_dir}/**/*.md")
+
+    def auto_fix_templates(self, template_dir: Path) -> bool:
+        """Attempt to auto-fix template linting issues.
+
+        Args:
+            template_dir: Directory containing template files
+
+        Returns:
+            True if fixes were applied successfully
+        """
+        return self._run_markdownlint_fix(f"{template_dir}/**/*.tmpl.md")
+
+    def auto_fix_generated_docs(self, output_dir: Path) -> bool:
+        """Attempt to auto-fix generated documentation linting issues.
+
+        Args:
+            output_dir: Directory containing generated markdown files
+
+        Returns:
+            True if fixes were applied successfully
+        """
+        return self._run_markdownlint_fix(f"{output_dir}/**/*.md")
+
+    def _run_markdownlint(self, pattern: str) -> tuple[bool, list[dict]]:
+        """Run markdownlint-cli2 on files matching pattern.
+
+        Args:
+            pattern: Glob pattern for files to lint
+
+        Returns:
+            Tuple of (success, errors)
+        """
+        cmd = ["markdownlint-cli2", pattern]
+        if self.config_file:
+            cmd.extend(["--config", str(self.config_file)])
+
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+
+            errors = []
+            if result.returncode != 0:
+                # Parse error output
+                for line in result.stderr.split("\n"):
+                    if line.strip() and ":" in line:
+                        parts = line.split(":", 3)
+                        if len(parts) >= 4:
+                            errors.append(
+                                {
+                                    "file": parts[0],
+                                    "line": parts[1] if parts[1].isdigit() else None,
+                                    "column": parts[2] if parts[2].isdigit() else None,
+                                    "rule": parts[3].split()[0]
+                                    if parts[3]
+                                    else "unknown",
+                                    "message": parts[3]
+                                    if parts[3]
+                                    else "Unknown error",
+                                }
+                            )
+
+            return result.returncode == 0, errors
+
+        except FileNotFoundError:
+            raise RuntimeError(
+                "markdownlint-cli2 not found. Install with: npm install -g markdownlint-cli2"
+            )
+
+    def _run_markdownlint_fix(self, pattern: str) -> bool:
+        """Run markdownlint-cli2 with --fix flag.
+
+        Args:
+            pattern: Glob pattern for files to fix
+
+        Returns:
+            True if fixes were applied successfully
+        """
+        cmd = ["markdownlint-cli2", "--fix", pattern]
+        if self.config_file:
+            cmd.extend(["--config", str(self.config_file)])
+
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+
+            return result.returncode == 0
+
+        except FileNotFoundError:
+            raise RuntimeError(
+                "markdownlint-cli2 not found. Install with: npm install -g markdownlint-cli2"
+            )
+
+    def generate_lint_report(self, errors: list[dict], output_file: Path) -> None:
+        """Generate a JSON report of linting errors for CI/CD integration.
+
+        Args:
+            errors: List of error dictionaries from linting
+            output_file: Path to write JSON report
+        """
+        report = {
+            "total_errors": len(errors),
+            "errors_by_rule": {},
+            "errors_by_file": {},
+            "errors": errors,
+        }
+
+        # Group errors by rule
+        for error in errors:
+            rule = error.get("rule", "unknown")
+            if rule not in report["errors_by_rule"]:
+                report["errors_by_rule"][rule] = 0
+            report["errors_by_rule"][rule] += 1
+
+        # Group errors by file
+        for error in errors:
+            file_path = error.get("file", "unknown")
+            if file_path not in report["errors_by_file"]:
+                report["errors_by_file"][file_path] = 0
+            report["errors_by_file"][file_path] += 1
+
+        with open(output_file, "w") as f:
+            json.dump(report, f, indent=2)
+
+
+def apply_markdown_fixes(content: str) -> str:
+    """Apply common markdown fixes to content.
+
+    Args:
+        content: Markdown content to fix
+
+    Returns:
+        Fixed markdown content
+    """
+    # Ensure trailing newline
+    content = content.rstrip() + "\n"
+
+    # Fix list marker spacing (convert double spaces to single)
+    import re
+
+    content = re.sub(r"^(\s*)-  ", r"\1- ", content, flags=re.MULTILINE)
+    content = re.sub(r"^(\s*)\d+\.  ", r"\1\d+. ", content, flags=re.MULTILINE)
+
+    # Add blank lines around headings
+    content = re.sub(r"\n(#{1,6}\s+.*)\n(?!\n)", r"\n\1\n\n", content)
+    content = re.sub(r"(?<!\n)\n(#{1,6}\s+.*)\n", r"\n\n\1\n", content)
+
+    # Add blank lines around fenced code blocks
+    content = re.sub(r"\n```(\w*)\n(?!\n)", r"\n\n```\1\n", content)
+    content = re.sub(r"(?<!\n)\n```(\w*)\n", r"\n\n```\1\n", content)
+    content = re.sub(r"\n```\n(?!\n)", r"\n```\n\n", content)
+    content = re.sub(r"(?<!\n)\n```\n", r"\n\n```\n", content)
+
+    return content
+
+
+def break_long_lines(content: str, max_length: int = 100) -> str:
+    """Break long lines at word boundaries.
+
+    Args:
+        content: Markdown content
+        max_length: Maximum line length
+
+    Returns:
+        Content with lines broken at word boundaries
+    """
+    lines = content.split("\n")
+    fixed_lines = []
+
+    for line in lines:
+        if len(line) <= max_length:
+            fixed_lines.append(line)
+            continue
+
+        # Skip code blocks and headings
+        if line.startswith("```") or line.startswith("#"):
+            fixed_lines.append(line)
+            continue
+
+        # Break at word boundaries
+        words = line.split(" ")
+        current_line = ""
+
+        for word in words:
+            if len(current_line + " " + word) <= max_length:
+                if current_line:
+                    current_line += " " + word
+                else:
+                    current_line = word
+            else:
+                if current_line:
+                    fixed_lines.append(current_line)
+                current_line = word
+
+        if current_line:
+            fixed_lines.append(current_line)
+
+    return "\n".join(fixed_lines)
+
+
+# 🍲🥄📄🪄

plating/models.py

@@ -0,0 +1,75 @@
+#
+# plating/models.py
+#
+"""Data models for documentation generation."""
+
+from typing import Any
+
+from attrs import define, field
+
+
+@define
+class ProviderInfo:
+    """Information about a Pyvider provider."""
+
+    name: str
+    description: str
+    short_name: str = ""
+    rendered_name: str = ""
+    schema_markdown: str = ""
+    has_example: bool = False
+    example_file: str = ""
+
+    def __attrs_post_init__(self):
+        if not self.short_name:
+            self.short_name = self.name
+        if not self.rendered_name:
+            self.rendered_name = self.name
+
+
+@define
+class ResourceInfo:
+    """Information about a resource or data source."""
+
+    name: str
+    type: str  # "Resource", "Data Source", or "Function"
+    description: str
+    schema_markdown: str = ""
+    schema: dict[str, Any] | None = None
+    has_example: bool = False
+    example_file: str = ""
+    has_import: bool = False
+    import_file: str = ""
+    has_import_id_config: bool = False
+    import_id_config_file: str = ""
+    has_import_identity_config: bool = False
+    import_identity_config_file: str = ""
+    # Co-located documentation fields
+    examples: dict[str, str] = field(factory=dict)
+    import_docs: str = ""
+    colocated_notes: str = ""
+    migration: str = ""
+
+
+@define
+class FunctionInfo:
+    """Information about a provider-defined function."""
+
+    name: str
+    type: str = "Function"
+    description: str = ""
+    summary: str = ""
+    has_example: bool = False
+    example_file: str = ""
+    signature_markdown: str = ""
+    arguments_markdown: str = ""
+    has_variadic: bool = False
+    variadic_argument_markdown: str = ""
+    # Co-located documentation fields
+    examples: dict[str, str] = field(factory=dict)
+    import_docs: str = ""
+    colocated_notes: str = ""
+    migration: str = ""
+
+
+# 🍲🥄📊🪄