Metadata-Version: 2.4
Name: cacao
Version: 1.0.0
Summary: A flexible documentation generator with plugin support
Home-page: https://github.com/jhd3197/CacaoDocs
Author: Juan Denis
Author-email: juan@vene.co
Project-URL: Bug Reports, https://github.com/yourusername/cacao/issues
Project-URL: Source, https://github.com/yourusername/cacao
Project-URL: Documentation, https://github.com/yourusername/cacao#readme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=2.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: markdown2>=2.4.0
Requires-Dist: beautifulsoup4>=4.9.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: python-dotenv>=0.19.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CacaoDocs

A flexible documentation generator with plugin support for Python applications.

## Features

- **Plugin System**: Easily extend functionality with custom plugins
  - Parser plugins for different documentation formats
  - Renderer plugins for custom output formats
  - Data transformer plugins for custom processing
  - Storage plugins for different storage backends
  - Search plugins for enhanced documentation search

- **Built-in Plugins**:
  - Markdown Parser: Parse markdown-formatted documentation
  - HTML Renderer: Generate beautiful HTML documentation
  - OpenAPI Generator: Generate OpenAPI/Swagger specifications

- **Error Handling**:
  - Centralized error management
  - Custom error types and handling
  - Detailed error logging
  - User-friendly error messages

- **Configuration**:
  - YAML-based configuration
  - Customizable themes
  - Plugin configuration support
  - Environment variable support

## Installation

```bash
pip install -r requirements.txt
```

## Usage

1. Basic setup:

```python
from cacao.core.documentation import CacaoDocs

# Initialize CacaoDocs
CacaoDocs.load_config()

# Use the decorator to document API endpoints
@CacaoDocs.doc_api(doc_type="api", tag="users")
def my_endpoint():
    """
    Method: GET
    Version: v1
    Status: Production
    
    Description:
        Example endpoint description.
    
    Responses:
        200:
            description: "Success"
            example: {"status": "ok"}
    """
    pass
```

2. Configuration (cacao.yaml):

```yaml
title: "My API Documentation"
description: "Comprehensive API documentation"
version: "1.0.0"
theme:
  primary_color: "#4CAF50"
  secondary_color: "#8b5d3b"
verbose: true
plugin_directory: "plugins"
```

3. Creating a Custom Plugin:

```python
from cacao.plugins.base_plugin import BasePlugin

class MyCustomPlugin(BasePlugin):
    def initialize(self) -> None:
        # Setup plugin
        pass
        
    def cleanup(self) -> None:
        # Cleanup resources
        pass
```

## Project Structure

```
cacao/
â”œâ”€â”€ core/
â”‚   â”œâ”€â”€ config.py         # Configuration management
â”‚   â”œâ”€â”€ documentation.py  # Main CacaoDocs class
â”‚   â””â”€â”€ parser.py        # Core documentation parser
â”œâ”€â”€ plugins/
â”‚   â”œâ”€â”€ base_plugin.py    # Base plugin interfaces
â”‚   â”œâ”€â”€ plugin_manager.py # Plugin lifecycle management
â”‚   â”œâ”€â”€ markdown_parser.py # Markdown parsing plugin
â”‚   â”œâ”€â”€ html_renderer.py  # HTML rendering plugin
â”‚   â””â”€â”€ openapi_generator.py # OpenAPI generation plugin
â”œâ”€â”€ templates/
â”‚   â””â”€â”€ default.html     # Default HTML template
â””â”€â”€ utils/
    â””â”€â”€ error_handler.py # Error handling system
```

## Plugin Development

1. Choose a plugin type:
   - ParserPlugin: Parse documentation from different formats
   - RendererPlugin: Generate output in different formats
   - TransformerPlugin: Transform documentation data
   - StoragePlugin: Store documentation in different backends
   - SearchPlugin: Implement custom search functionality

2. Implement the required methods:
   - `initialize()`: Setup plugin resources
   - `cleanup()`: Cleanup plugin resources
   - Plugin-specific methods based on the plugin type

3. Add plugin configuration to cacao.yaml:

```yaml
plugins:
  my_plugin:
    option1: value1
    option2: value2
```

## Error Handling

The error handling system provides:

- Custom exception types for different errors
- Error logging with configurable levels
- Error formatting for API responses
- Error handler decorator for consistent handling

Example:

```python
from cacao.utils.error_handler import ErrorHandler, CacaoDocsError

@ErrorHandler.error_handler("CustomError")
def my_function():
    raise CacaoDocsError("Something went wrong", "CustomError")
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - see LICENSE file for details
