cod8a

cod8a pronounced codetta, is a code documentation and visualization tool for Python and .NET projects.

Installation

Prerequisites

• Python 3.9+
• .NET 10.0 Runtime or SDK (Required only for C#/.NET analysis)

From PyPI

Install cod8a directly using pip:

pip install cod8a

Usage

The tool uses a CLI interface to analyze code and generate mermaid diagrams.

UML Diagrams

Generate Mermaid-compatible diagrams (Class, Sequence, Flowchart):

# General syntax
cod8a uml -p <path_to_source> -d <diagram_type>

# Generate a class diagram (default)
cod8a uml -p <path_to_source>

# Generate a sequence diagram
cod8a uml -p <path_to_source> -d sequence

# Generate a flowchart
cod8a uml -p <path_to_source> -d flow

# Summarize a large project (omit fields/methods)
cod8a uml -p <path_to_source> --summarize

# Force full diagram details for a large file
cod8a uml -p <path_to_source> --no-summarize

Diagram Type Options:

• Class: class, c
• Sequence: sequence, seq, s
• Flowchart: flowchart, flow, f

Visualizing Diagrams

The generated .mmd files can be visualized using several tools:

• Mermaid Live Editor: Simply copy and paste the generated output into the editor to view and export the diagram as an image (SVG, PNG).
• VS Code: Install the Mermaid Editor or Markdown Mermaid Preview extension to see live previews directly in your IDE.
• GitHub: GitHub natively renders Mermaid diagrams in Markdown files.

Samples

Below are detailed example Mermaid diagrams generated by cod8a based on its own src/cod8a/models/models.py file:

• Class Diagram Example
• Flowchart Example
• Sequence Diagram Example

CLI Options

• -p, --path: Path to the file or directory to analyze.
• -d, --diagram: Type of diagram to generate (default: class).
• -o, --output: Output file path (saves as .mmd).
• -s, --summarize / --no-summarize: Enable or disable diagram summarization. When enabled, details like fields and methods are omitted (useful for large files). Defaults to auto-summarize for large files.

Documentation (In development)

Note: This feature is currently in development.

Generate Markdown documentation from code structure:

# Not yet implemented
cod8a doc -p <path_to_source>

Features

• Mermaid Integration: Generates high-quality Mermaid.js diagrams for visualization.
  • Supported Diagrams: Class, Sequence, and Flowchart diagrams.
• C# Support: Uses a Roslyn-based analyzer targeting .NET 10.0 to extract deep structural information.
• Python Support: Uses AST-based parsing for Python files.
• Markdown Documentation (TODO): Detailed markdown generation for code documentation is currently in development.

Development

Setup

1. Fork the repository on GitHub.
2. Clone your fork:

git clone https://github.com/yourusername/cod8a.git
cd cod8a

Development Options

1. Local Setup

3. Install Python dependencies:

Using Poetry (recommended):

poetry install

4. Optional: Ensure .NET 10.0 is installed (if documenting C#)

dotnet --version

2. VS Code Dev Container (Recommended)

If you use VS Code, you can skip the local setup by using the provided Dev Container. It comes pre-configured with Python 3.13, .NET 10.0, and Poetry.

• Simply open the project in VS Code and click "Reopen in Container" when prompted.

3. Docker

You can also run cod8a as a standalone container without installing any dependencies locally:

# Build the image
docker build -t cod8a .

# Run the tool
docker run -v $(pwd):/app/data cod8a uml -p /app/data/src