Adjusting documentation and releasing the version v0.1.0

Author: rafaelherik

.github/workflows/release.yml

@@ -53,3 +53,25 @@ jobs:
         TWINE_USERNAME: __token__
         TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
       run: twine upload dist/*
+
+  docs:
+    needs: release
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install MkDocs and Material theme
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material
+
+      - name: Deploy documentation to GitHub Pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: mkdocs gh-deploy --force --clean --remote-branch gh-pages

README.md

@@ -1,6 +1,7 @@
 # tfsumpy - Terraform Plan Summary Tool
 
 [![CI](https://github.com/rafaelherik/tfsumpy/actions/workflows/ci.yaml/badge.svg)](https://github.com/rafaelherik/tfsumpy/actions/workflows/ci.yaml)
+[![PyPI](https://img.shields.io/pypi/v/tfsumpy.svg)](https://pypi.org/project/tfsumpy/)
 
 tfsumpy is a Python-based tool that summarizes Terraform plan files to provide a clear overview of infrastructure changes. It helps DevOps teams review infrastructure changes more effectively by providing detailed plan summaries in different formats.
 
@@ -195,3 +196,29 @@ See all available tasks:
 ```bash
 task --list
 ```
+
+## 🧩 Extending tfsumpy (Plugins)
+
+tfsumpy supports plug-and-play extensions! You can add your own analyzers or reporters by dropping Python files in a `plugins/` directory (or specify a custom directory with `--plugin-dir`).
+
+- Each plugin should define a `register(context)` function that registers analyzers/reporters.
+- tfsumpy will automatically load and register all plugins in the directory at startup.
+
+**Example plugin:**
+```python
+from tfsumpy.analyzer import AnalyzerInterface, AnalyzerResult
+class MyCostAnalyzer(AnalyzerInterface):
+    @property
+    def category(self): return "cost"
+    def analyze(self, context, **kwargs):
+        return AnalyzerResult(category="cost", data={"total_cost": 42})
+def register(context):
+    context.register_analyzer(MyCostAnalyzer())
+```
+
+**Usage:**
+```bash
+tfsumpy plan.json --plugin-dir my_plugins/
+```
+
+See [Extending tfsumpy](docs/extending.md) for more details and advanced examples.

docs/api/analyzers.md

@@ -2,50 +2,93 @@
 
 ## Overview
 
-Analyzers in tfsumpy are responsible for analyzing different aspects of Terraform plans. Each analyzer focuses on a specific type of analysis (plan).
+Analyzers in **tfsumpy** are responsible for processing and interpreting Terraform plan files. Each analyzer implements a specific type of analysis. The primary built-in analyzer is the `PlanAnalyzer`, which summarizes resource changes in a Terraform plan.
+
+---
 
 ## Base Analyzer Interface
 
+All analyzers must implement the `AnalyzerInterface`:
+
 ```python
 from abc import ABC, abstractmethod
-from typing import Any
+from tfsumpy.analyzer import AnalyzerResult
 
 class AnalyzerInterface(ABC):
     @property
     @abstractmethod
     def category(self) -> str:
-        """Return the analyzer category"""
+        """Return the analyzer category (e.g., 'plan')."""
         pass
-    
+
     @abstractmethod
-    def analyze(self, context: 'Context', **kwargs) -> 'AnalyzerResult':
-        """Perform analysis and return results"""
+    def analyze(self, context: 'Context', **kwargs) -> AnalyzerResult:
+        """
+        Perform analysis and return results.
+
+        Args:
+            context: The tfsumpy Context object
+            **kwargs: Additional arguments (e.g., plan_path)
+        Returns:
+            AnalyzerResult: The result of the analysis
+        """
         pass
 ```
 
-## Plan Analyzer
+---
 
-The `PlanAnalyzer` processes Terraform plan files and extracts change information.
+## PlanAnalyzer
+
+The `PlanAnalyzer` is the default analyzer for Terraform plan files. It parses the plan JSON and produces a summary of all resource changes.
+
+**Example usage:**
 
 ```python
 from tfsumpy.plan.analyzer import PlanAnalyzer
+from tfsumpy.context import Context
 
-analyzer = PlanAnalyzer(context)
-result = analyzer.analyze(context, plan_path="plan.json")
+context = Context()
+plan_analyzer = PlanAnalyzer(context)
+result = plan_analyzer.analyze(context, plan_path="plan.json")
+
+print(result.data["total_changes"])
+print(result.data["resources"])  # List of resource change dicts
 ```
 
-## Creating Custom Analyzers
+**Parameters:**
+- `context`: The tfsumpy Context object (handles config, redaction, etc.)
+- `plan_path`: Path to the Terraform plan JSON file
+
+**Returns:**
+- `AnalyzerResult` with a summary of changes, including:
+  - `total_changes`: int
+  - `change_breakdown`: dict (create/update/delete counts)
+  - `resources`: list of resource change dicts
 
-To create a custom analyzer:
+---
+
+## Extending: Custom Analyzers
+
+You can create your own analyzer by subclassing `AnalyzerInterface`:
 
 ```python
 from tfsumpy.analyzer import AnalyzerInterface, AnalyzerResult
 
-class CustomAnalyzer(AnalyzerInterface):
+class MyCustomAnalyzer(AnalyzerInterface):
     @property
     def category(self) -> str:
         return "custom"
-    
-    def analyze(self, context: 'Context', **kwargs) -> AnalyzerResult:
-        # Implement analysis logic
-        return AnalyzerResult(category="custom", data={}) 
+
+    def analyze(self, context, **kwargs) -> AnalyzerResult:
+        # Custom analysis logic here
+        return AnalyzerResult(category="custom", data={"result": "ok"})
+```
+
+Register your custom analyzer with the tfsumpy `Context` to use it in your workflow.
+
+---
+
+## Notes
+- All analyzers should return an `AnalyzerResult`.
+- The `PlanAnalyzer` is the main entry point for plan file analysis.
+- See the [Models API](models.md) for details on the data structures returned by analyzers.

docs/api/models.md

@@ -2,37 +2,63 @@
 
 ## Overview
 
-tfsumpy uses several data models to represent different aspects of infrastructure analysis.
+**tfsumpy** uses several data models to represent the results of plan analysis and reporting. Understanding these models is essential for extending tfsumpy or integrating it into other tools.
 
-## Resource Change Model
+---
+
+## ResourceChange
+
+Represents a single resource change in a Terraform plan.
 
 ```python
 from dataclasses import dataclass
 from typing import Dict, List
 
 @dataclass
 class ResourceChange:
-    action: str
-    resource_type: str
-    identifier: str
-    changes: List[str]
-    module: str = 'root'
-    before: Dict = None
-    after: Dict = None
+    action: str           # 'create', 'update', or 'delete'
+    resource_type: str    # e.g., 'aws_s3_bucket'
+    identifier: str       # Resource address (e.g., 'aws_s3_bucket.my_bucket')
+    changes: List[str]    # List of changed attributes (optional/legacy)
+    module: str = 'root'  # Module path (e.g., 'root', 'network.vpc')
+    before: Dict = None   # State before the change
+    after: Dict = None    # State after the change
 ```
 
-## Analysis Result Model
+**Fields:**
+- `action`: The type of change ('create', 'update', 'delete')
+- `resource_type`: The Terraform resource type
+- `identifier`: The resource address in the plan
+- `changes`: List of changed attributes (may be empty)
+- `module`: Module path (default 'root')
+- `before`: Dictionary of the resource's state before the change
+- `after`: Dictionary of the resource's state after the change
+
+---
+
+## AnalyzerResult
+
+Represents the result of an analyzer (e.g., PlanAnalyzer).
 
 ```python
+from dataclasses import dataclass
+from typing import Any
+
 @dataclass
 class AnalyzerResult:
-    category: str
-    data: Any
+    category: str   # e.g., 'plan'
+    data: Any      # Typically a dict with summary and resource changes
 ```
 
-## Using Models
+**Fields:**
+- `category`: The analyzer category (e.g., 'plan')
+- `data`: The analysis result (usually a dict with summary and resource changes)
+
+---
+
+## Example: Using Models
 
-### Resource Change Example
+### ResourceChange Example
 
 ```python
 change = ResourceChange(
@@ -45,22 +71,21 @@ change = ResourceChange(
 )
 ```
 
-### Analysis Result Example
+### AnalyzerResult Example
 
 ```python
 result = AnalyzerResult(
-    category="terraform_plan_summary",
+    category="plan",
     data={
-        "resource_changes": [
-            ResourceChange(
-                action="create",
-                resource_type="aws_s3_bucket",
-                identifier="my_bucket",
-                changes=["bucket_name", "versioning"],
-                before={},
-                after={"bucket_name": "new-bucket", "versioning": True}
-            )
-        ]
+        "total_changes": 1,
+        "change_breakdown": {"create": 1, "update": 0, "delete": 0},
+        "resources": [change]
     }
 )
-``` 
+```
+
+---
+
+## Notes
+- The `data` field in `AnalyzerResult` is typically a dictionary with keys like `total_changes`, `change_breakdown`, and `resources` (a list of `ResourceChange` objects or dicts).
+- See the [Analyzers API](analyzers.md) and [Reporters API](reporters.md) for how these models are used in practice. 

docs/api/reporters.md

@@ -2,53 +2,88 @@
 
 ## Overview
 
-Reporters in tfsumpy are responsible for formatting and displaying analysis results. Each reporter corresponds to a specific type of analysis output (plan).
+Reporters in **tfsumpy** are responsible for formatting and displaying the results of plan analysis. Each reporter implements a specific output format (e.g., CLI, Markdown, JSON). The primary built-in reporter is the `PlanReporter`, which provides human-friendly and Markdown output for Terraform plan summaries.
+
+---
 
 ## Base Reporter Interface
 
+All reporters must implement the `ReporterInterface`:
+
 ```python
 from abc import ABC, abstractmethod
-from typing import Any
 
 class ReporterInterface(ABC):
     @property
     @abstractmethod
     def category(self) -> str:
-        """Return the reporter category"""
+        """Return the reporter category (e.g., 'plan')."""
         pass
-    
+
     @abstractmethod
     def print_report(self, data: Any, **kwargs) -> None:
-        """Format and print the analysis results"""
+        """
+        Format and print the analysis results.
+
+        Args:
+            data: The analysis results (typically a dict)
+            **kwargs: Additional display options (e.g., show_changes, show_details)
+        """
         pass
 ```
 
-## Plan Reporter
+---
 
-The `PlanReporter` formats and displays Terraform plan analysis results.
+## PlanReporter
+
+The `PlanReporter` is the default reporter for plan summaries. It supports both colorized CLI output and Markdown output for sharing or documentation.
+
+**Example usage:**
 
 ```python
 from tfsumpy.plan.reporter import PlanReporter
 
 reporter = PlanReporter()
-reporter.print_report(plan_results)
+reporter.print_report(plan_results, show_changes=True)
+reporter.print_report_markdown(plan_results, show_changes=True)
 ```
 
-## Creating Custom Reporters
+**Parameters:**
+- `data`: The analysis results (from `PlanAnalyzer`)
+- `show_changes`: Show detailed attribute changes (bool)
+- `show_details`: Show full resource details (bool)
+
+**Output:**
+- Prints formatted summary to stdout (or to a file/stream if specified)
+- Markdown output is suitable for PRs, documentation, or compliance
 
-To create a custom reporter:
+---
+
+## Extending: Custom Reporters
+
+You can create your own reporter by subclassing `ReporterInterface` (optionally inheriting from `BaseReporter` for convenience):
 
 ```python
 from tfsumpy.reporter import ReporterInterface
 from tfsumpy.reporters.base_reporter import BaseReporter
 
-class CustomReporter(BaseReporter, ReporterInterface):
+class MyCustomReporter(BaseReporter, ReporterInterface):
     @property
     def category(self) -> str:
         return "custom"
-    
+
     def print_report(self, data: Any, **kwargs) -> None:
-        # Implement report formatting and display logic
-        self._write("Custom Report\n")
-        self._write("=============\n")
-        # Add custom formatting logic 
+        # Custom formatting logic here
+        self._write("My Custom Report\n")
+        self._write("=================\n")
+        # ...
+```
+
+Register your custom reporter with the tfsumpy `Context` to use it in your workflow.
+
+---
+
+## Notes
+- The `PlanReporter` supports both CLI and Markdown output.
+- You can direct output to a file or stream by passing a custom `output` to `BaseReporter`.
+- See the [Models API](models.md) for details on the data structures passed to reporters.