UI-ang Documentation Generator

A TypeScript-based tool for processing and transforming UI-ang documentation into structured JSON and HTML outputs, including SCSS variable processing.

Overview

This tool processes Angular documentation JSON (generated from tools like Compodoc) and SCSS files to transform them into:

• Individual JSON files for components, directives, and pipes
• SCSS variable documentation
• A combined documentation JSON file
• HTML documentation pages

Features

• Processes UI-ang components, directives, and pipes
• Extracts and documents SCSS variables and their usage
• Strips redundant suffixes (e.g., "Component", "Directive", "Pipe") from output filenames
• Supports type aliases documentation
• Generates both JSON and HTML outputs
• Maintains version control of documentation (v11 and v12 support)
• Creates organized directory structure for outputs

Project Structure

├── src/
│   ├── processors/         # Documentation processing logic
│   │   ├── component-processor.ts
│   │   ├── directive-processor.ts
│   │   ├── pipe-processor.ts
│   │   └── scss-processor.ts
│   ├── generators/         # HTML generation logic
│   │   └── html-generator.ts
│   ├── templates/         # Template files
│   │   ├── scss-base.ts
│   │   └── scss/_variables.scss
│   ├── utils/            # Utility functions
│   │   └── processors/
│   │       └── shared.ts
│   ├── interfaces/        # TypeScript interfaces
│   ├── constants.ts       # Project constants
│   └── index.ts          # Main entry point
├── input/                # Input documentation files
│   ├── v11/             # Version 11 input files
│   └── v12/             # Version 12 input files
└── docs/              # Generated documentation
    ├── v11/             # Version 11 output
    └── v12/             # Version 12 output

Input Requirements

The tool expects:

1. An input JSON file (configured in constants) that contains Angular documentation with the following structure:
   • Components section
   • Directives section
   • Pipes section
   • Type aliases (under miscellaneous)
2. SCSS files containing UI-ang variables and styles

Output

The tool generates:

1. Individual JSON files for each component, directive, and pipe
2. SCSS variable documentation
3. A combined JSON file containing all documentation (ui-ang.json)
4. HTML documentation pages for easy viewing

Usage

# Install dependencies
npm install

# Run the documentation generator
npm run parse

Version Control

The tool maintains separate documentation for different versions of UI-ang (v11 and v12), making it easy to track documentation across releases.

Dependencies

• Node.js
• TypeScript
• File system access for reading/writing documentation files

Error Handling

• Ensures output directories exist before writing files
• Safely processes documentation entries with null checks
• Maintains type safety through TypeScript interfaces
• Validates SCSS variable definitions and usage