Skip to content

Tools & Utilities

This directory contains tools and utilities for the Odoo migration project, primarily focused on diagram generation and documentation automation.

🛠️ Available Tools

📊 PlantUML Diagram Generator

  • plantuml.jar - PlantUML engine for generating diagrams
  • generate-diagrams.ps1 - PowerShell script for batch diagram generation

🌐 Local Documentation Server

  • serve-local.ps1 - PowerShell script for local testing
  • serve-local.bat - Windows batch file for local testing
  • ../serve-local.py - Python HTTP server (cross-platform)
  • ../serve-python.bat - Windows batch wrapper for Python server

🚀 Quick Start

Prerequisites

  • Java 8 or higher (for PlantUML diagram generation)
  • PowerShell (for Windows scripts)
  • Python 3.6+ (for Python server option)

Installation

  1. The plantuml.jar file is already downloaded in this directory
  2. The generate-diagrams.ps1 script is ready to use

📋 Usage

Generate All Diagrams

.\tools\generate-diagrams.ps1

Generate Specific Diagram

.\tools\generate-diagrams.ps1 "docs\diagrams\Odoo-Contact-Migration-Phases.puml"

Manual Generation

java -jar tools\plantuml.jar docs\diagrams\Odoo-Contact-Migration-Phases.puml

Start Local Documentation Server

Option 1: PowerShell (Windows/Linux/macOS)

.\tools\serve-local.ps1

# Custom port
.\tools\serve-local.ps1 8080

Option 2: Windows Batch

.\tools\serve-local.bat

Option 3: Python Server (Cross-platform)

# Basic usage
python serve-local.py

# Custom port
python serve-local.py --port 3000

# Allow external connections
python serve-local.py --host 0.0.0.0

# Auto-find available port
python serve-local.py --auto-port

# Don't open browser automatically
python serve-local.py --no-browser

Option 4: Python Batch Wrapper (Windows)

.\serve-python.bat

Access Local Documentation

  • Open your browser to: http://localhost:8000
  • Navigate through the documentation
  • Test all links and images locally

📁 Output

  • Generated PNG files are saved in the diagrams/ directory
  • Each .puml file will create a corresponding .png file
  • The script provides colored output showing success/failure status

🔧 Troubleshooting

PlantUML Issues

"plantuml.jar file not found"

  • Ensure the JAR file is in the tools/ directory
  • Download from: https://plantuml.com/download

Java not found

  • Ensure Java is installed and in your PATH
  • Test with: java -version

Server Issues

PowerShell permission errors

  • Run PowerShell as Administrator if needed
  • Check file permissions on the tools directory

Python server issues

  • Ensure Python 3.6+ is installed: python --version
  • Port already in use: Try --auto-port flag or different port
  • Permission denied: Try running as administrator (Windows) or with sudo (Linux/macOS)

Browser not opening automatically

  • Manually navigate to the URL shown in the terminal
  • Use --no-browser flag to disable auto-opening

📖 Integration with Documentation

The generated PNG files can be embedded in markdown documents:

![Diagram Description](../docs/diagrams/diagram-name.png)

This approach is more reliable than inline PlantUML code blocks and works with all markdown renderers.

🎯 Best Practices

  1. Keep diagrams updated - Regenerate when source files change
  2. Use consistent naming - Follow established naming conventions
  3. Version control - Include both source (.puml) and output (.png) files
  4. Documentation integration - Reference generated diagrams in relevant docs
  5. Testing - Test diagram generation in staging before production