Documentation - HkDevs CodeForge Database Studio

Phase 6: Documentation Generator

Comprehensive automated documentation system that generates professional database documentation, ERD diagrams, and schema snapshots with multiple export formats and intelligent analysis capabilities.

Overview

Intelligent Documentation

Automatically analyze your database structure and generate comprehensive documentation with minimal configuration.

Complete database analysis
Model discovery and mapping
Relationship visualization
Performance metrics inclusion

Multiple Export Formats

Generate documentation in various formats suitable for different audiences and use cases.

Markdown for developers
HTML for web viewing
PDF for presentations
JSON for API integration

Documentation Features

Schema Snapshots

Version-controlled schema captures

ERD Generation

Automatic entity relationship diagrams

Statistics

Comprehensive database metrics

Comparison

Schema version comparison tools

Automated Generation

Complete Database Analysis

The documentation generator performs comprehensive analysis of your database structure, models, and relationships.

Table Structure

• Column definitions and types
• Constraints and indexes
• Primary and foreign keys
• Table statistics and sizes

Model Discovery

• Eloquent model mapping
• Relationship definitions
• Fillable and guarded attributes
• Cast definitions and methods

Relationship Analysis

• Foreign key relationships
• Model relationships
• Cardinality analysis
• Dependency mapping

Quick Generation Command:

php artisan db-manager:generate-docs --format=markdown --title="Database Documentation"

Flexible Documentation Scope

Choose exactly what to include in your documentation based on your needs and audience.

Full Schema Documentation

Complete database documentation including all tables, models, and relationships.

--scope=full_schema

Models Only

Document only tables that have corresponding Eloquent models.

--scope=models_only

Selected Tables

Choose specific tables to include in the documentation.

--scope=selected_tables --tables=users,posts

Single Table

Focused documentation for a specific table with detailed analysis.

--scope=single_table --table=users

Visual Documentation Features

Generate visual representations of your database structure for better understanding and communication.

Entity Relationship Diagrams (ERD)

Automatically generate professional ERD diagrams showing table relationships and cardinalities.

Dependency Graphs

Visual representation of table dependencies and foreign key relationships.

Statistics Charts

Include charts showing database statistics, table sizes, and relationship distribution.

Schema Snapshots

Version-Controlled Schema Capture

Create point-in-time snapshots of your database schema for version control, comparison, and historical analysis.

Snapshot Features:

Complete schema capture
Model relationship mapping
Validation rule extraction
Policy information capture
Automatic hash generation

Use Cases:

Pre-deployment backups
Schema evolution tracking
Documentation generation
Project collaboration
Compliance reporting

Create Schema Snapshot:

php artisan db-manager:create-snapshot --name="Pre-deployment snapshot" --description="Schema before feature release"

Schema Comparison

Compare any two schema snapshots to identify changes, additions, and modifications over time.

Added Tables

New tables and their structures

Modified Tables

Changed columns and constraints

Removed Tables

Deleted tables and relationships

Advanced Comparison Features:

• Column type and constraint changes
• Index additions and modifications
• Foreign key relationship changes
• Model mapping differences
• Performance impact analysis

Baseline Management

Mark specific snapshots as baselines for long-term comparison and change tracking.

Baseline Snapshots

Mark important schema versions as baselines for consistent comparison reference points.

Mark as Baseline:

php artisan db-manager:create-snapshot --name="Production baseline" --baseline

Export Formats

Multiple Output Formats

Generate documentation in various formats to meet different requirements and audiences.

Markdown

Developer-friendly format for wikis and documentation portals

--format=markdown

HTML

Styled web pages ready for sharing and browser viewing

--format=html

PDF

Professional documents for reports and presentations

--format=pdf

JSON

Structured data for API integration and automation

--format=json

Format-Specific Features

Each export format is optimized for its intended use case with specific enhancements.

Markdown Features

• GitHub-flavored markdown syntax
• Table of contents generation
• Code syntax highlighting
• Cross-reference links

• Collapsible sections
• Badge and status indicators
• Mermaid diagram support
• Wiki-ready formatting

HTML Features

• Responsive design layout
• Interactive navigation menu
• Search functionality
• Themed styling options

• Collapsible content sections
• Inline SVG diagrams
• Print-optimized styles
• Mobile-friendly interface

PDF Features

• Professional page layout
• Headers and footers
• Bookmarks and navigation
• High-quality diagrams

• Table of contents with page numbers
• Watermarks and branding
• Print-ready formatting
• Metadata embedding

Batch Generation

Generate multiple formats simultaneously for comprehensive documentation packages.

Generate All Formats:

php artisan db-manager:generate-docs --format=all --title="Complete Database Documentation"

Batch Generation Benefits:

• Consistent content across all formats
• Simultaneous generation saves time
• Automatic file organization
• Comprehensive documentation packages

Customization

Custom Templates

Customize documentation templates to match your organization's branding and requirements.

Template Configuration:

// config/codeforge-database-studio.php
'documentation' => [
    'templates' => [
        'markdown' => resource_path('templates/docs/markdown.blade.php'),
        'html' => resource_path('templates/docs/html.blade.php'),
        'pdf' => resource_path('templates/docs/pdf.blade.php'),
    ],
    'styling' => [
        'brand_color' => '#3b82f6',
        'logo_path' => public_path('images/company-logo.png'),
        'footer_text' => 'Generated by CodeForge Database Studio',
    ],
]

Template Variables:

$title - Documentation title
$description - Project description
$tables - Table data array
$relationships - Relationship data
$models - Model mapping data
$statistics - Database statistics

Styling Options:

• Custom CSS for HTML output
• Brand colors and typography
• Company logos and watermarks
• Custom headers and footers
• Themed color schemes
• Layout customizations

Content Customization

Control what information is included and how it's presented in your documentation.

Content Sections

• Table of contents
• Database overview
• Table details
• Relationship diagrams
• Model documentation
• Statistics and metrics

Filtering Options

• Exclude system tables
• Hide empty tables
• Filter by table patterns
• Include/exclude specific columns
• Model relationship filtering
• Custom field grouping

Advanced Customization

Use custom generators and hooks to add project-specific information and formatting to your documentation.

Output Customization

Configure output paths, file naming, and organization for generated documentation.

// Custom output configuration
'output' => [
    'base_path' => storage_path('documentation'),
    'naming_pattern' => '{title}_{format}_{date}',
    'auto_cleanup' => true,
    'retention_days' => 30,
    'compression' => [
        'enabled' => true,
        'format' => 'zip', // zip, tar, gzip
    ],
]

Integration

Filament Admin Integration

Seamlessly integrated with the Filament admin interface for easy documentation management.

Management Features:

Visual documentation generator
Schema snapshot management
Generation history tracking
Download and preview options

Monitoring Features:

Generation status tracking
File size and format metrics
Error logging and debugging
Performance monitoring

API Integration

Programmatic access to documentation generation and schema snapshot features.

Service Usage Example:

use HkDevs\CodeForgeStudio\Services\DocumentationGenerationService;
use HkDevs\CodeForgeStudio\Services\SchemaDocumentationService;

// Generate documentation programmatically
$generation = DocumentationGeneration::create([
    'title' => 'API Documentation',
    'format' => 'markdown',
    'scope' => 'models_only',
]);

$service = new DocumentationGenerationService($generation);
$service->generate();

// Create schema snapshot
$schemaService = new SchemaDocumentationService();
$snapshot = $schemaService->generateSchemaSnapshot('API Snapshot');

Documentation API

• Generate documentation
• List generated files
• Download documentation
• Delete old files

Snapshot API

• Create snapshots
• Compare snapshots
• List snapshot history
• Export snapshot data

CI/CD Integration

Automate documentation generation as part of your deployment pipeline.

GitHub Actions Example:

name: Generate Database Documentation
on:
  push:
    branches: [main]
    paths: ['database/**']

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
      - name: Generate Documentation
        run: |
          php artisan db-manager:create-snapshot --name="Release-${GITHUB_SHA}"
          php artisan db-manager:generate-docs --format=markdown --auto-download

Automation Benefits

• Always up-to-date documentation
• Automatic schema change detection
• Version-controlled documentation
• Integration with deployment workflows

Best Practices

Documentation Strategy

Develop a comprehensive documentation strategy that serves different audiences and use cases.

Regular Snapshot Schedule

Create snapshots before major schema changes, deployments, and feature releases for historical reference.

Audience-Specific Documentation

Generate different documentation formats for developers (Markdown), stakeholders (PDF), and systems (JSON).

Automation Integration

Integrate documentation generation into your CI/CD pipeline for always up-to-date documentation.

Version Control

Store documentation in version control alongside your code for historical tracking and project access.

Performance Optimization

Optimize documentation generation for large databases and complex schemas.

Large Database Tips:

Use selective scopes for faster generation
Generate documentation in off-peak hours
Cache schema analysis results
Use background job processing

Resource Management:

Configure memory limits appropriately
Clean up old documentation files
Monitor generation performance
Optimize database connections

Maintenance & Cleanup

Implement proper maintenance procedures to keep your documentation system efficient.

Automated Cleanup

Set up automated cleanup of old documentation and snapshots to prevent storage bloat.

php artisan database-manager:cleanup-docs --days=30

Performance Monitoring

Monitor generation times and file sizes to identify performance issues and optimization opportunities.