Lintro Documentation Hub

Welcome to the Lintro documentation! This hub provides comprehensive guides for using, configuring, and contributing to Lintro.

Quick Start: If you’re new to Lintro, start with the main README for installation and basic usage, then return here for detailed guides.

📚 Documentation Structure

For Users

New to Lintro? Start here:

• Getting Started - Installation, first steps, and basic usage
• Configuration Guide - Tool configuration and customization
• AI Features - AI-powered summaries, explanations, and fix suggestions
• AI review transports - API vs CLI profiles, credentials, timeouts, and cost provenance
• MCP Server - Optional stdio MCP server for agent hosts
• Docker Usage - Using Lintro with Docker

Integration Guides:

• GitHub Integration - CI/CD setup with GitHub Actions
• Pre-commit Integration - Run lintro as a pre-commit hook
• Tool Analysis - Detailed tool comparisons and capabilities

For Developers

Contributing to Lintro:

• Contributing Guide - Development setup and contribution guidelines
• Adding a New Tool - Step-by-step guide for integrating a new linting or formatting tool
• Testing Guide - Test layout, source mapping, markers, fixtures, and coverage

Architecture & Vision:

• Architecture Overview - Project vision, technical architecture, and roadmap
• Vision & Principles - Core principles (DRY, SOLID) and success criteria
• Technical Architecture - Design decisions and component relationships
• Architecture Decision Records - Discrete, searchable records of key decisions and their rationale
• Roadmap - Prioritized improvements and development phases
• Design Documents - Design and evaluation docs for larger or exploratory changes

Reference Documentation:

• Style Guide - Coding standards and best practices
• Self-Use Documentation - How Lintro uses itself
• Troubleshooting - Common issues and solutions

🚀 Quick Links

Most Common Tasks

Task	Documentation
Install Lintro	Main README → Installation
First time usage	Main README → Quick Start
Docker setup	Docker Usage → Quick Start
GitHub Actions	GitHub Integration → Quick Setup
AI features	AI Features → Quick Start
Configure tools	Configuration → Tool Configuration
Add new tool	Adding a New Tool Guide
Project vision	Architecture → Vision
Development roadmap	Architecture → Roadmap
Troubleshooting	Troubleshooting

By Use Case

📋 Code Quality Checking:

lintro check

→ Main README → Basic Usage

🛠️ Auto-fixing Issues:

lintro format

→ Main README → Advanced Usage

🧪 Running Tests:

lintro test

→ Pytest Analysis

🧠 AI-Powered Analysis:

Requires lintro[ai] extra, an API key, and ai.enabled: true.

lintro check --fix

AI Features Guide

🐳 Containerized Development:

./docker-lintro.sh check

→ Docker Usage Guide

⚙️ CI/CD Integration: → GitHub Integration Guide

📖 Documentation by Audience

End Users

Goal: Use Lintro effectively in projects

1. Main README - Quick start and basic usage
2. Configuration - Customize for your project
3. Docker Usage - Containerized workflows (optional)
4. GitHub Integration - CI/CD automation (optional)

Goal: Integrate Lintro into team workflows

1. GitHub Integration - Set up automated quality checks
2. Configuration - Project-wide configuration
3. Tool Analysis - Understand tool capabilities
4. Docker Usage - Standardized environments

Goal: Contribute to or extend Lintro

1. Contributing Guide - Development setup and guidelines
2. Style Guide - Code quality standards
3. Tool Analysis - Understanding tool integration patterns
4. Self-Use Documentation - How we use our own tool

🛠️ Supported Tools

Tool	Language/Format	Purpose	Documentation
Ruff	Python	Linting & Formatting	Config Guide
Black	Python	Formatting (Post-check)	Config Guide
pydoclint	Python	Docstring Validation	Analysis
Bandit	Python	Security Linting	Analysis
Pytest	Python	Test Runner	Analysis
Prettier	JS/TS/JSON/CSS	Code Formatting	Analysis
Yamllint	YAML	Syntax & Style	Config Guide
Markdownlint-cli2	Markdown	Style Checking	Config Guide
Actionlint	GitHub Workflows	Workflow Linting	Analysis
Hadolint	Dockerfile	Best Practices	Config Guide

📋 Command Reference

Basic Commands

# Check code for issues
lintro check

# Auto-fix issues where possible
lintro format

# Run tests
lintro test

# List available tools
lintro list-tools [OPTIONS]

Command Chaining

# Run multiple commands in sequence
lintro format, check, test

# With specific tools
lintro format --tools black, check --tools ruff, test

# Using aliases
lintro fmt, chk, tst

Common Options

--output-format grid        # Use grid output (recommended)
--tools ruff,prettier        # Run specific tools only
--output results.txt         # Save output to file
--group-by [file|code|auto]  # Group issues by type
--exclude "venv,node_modules" # Exclude patterns

Docker Commands

# Using the shell script (recommended)
./docker-lintro.sh check

# Using docker directly
docker run --rm -v "$(pwd):/code" lintro:latest check

🔍 Finding Information

Search by Topic

• Installation: Getting Started
• AI Features: AI Features Guide
• Configuration: Configuration Guide
• Docker: Docker Usage
• CI/CD: GitHub Integration
• Contributing: Contributing Guide, Adding a New Tool
• Tool Comparison: Tool Analysis

Search by Error/Issue

• “Tool not found”: Getting Started → Troubleshooting
• “Permission denied”: Docker Usage → Troubleshooting
• “Configuration not working”: Configuration → Troubleshooting
• “Workflow not triggering”: GitHub Integration → Troubleshooting

🆕 Recent Updates

• AI-powered intelligence - AI summaries and interactive fix suggestions (--fix)
• Security audit framework - Comprehensive security verification for workflows and scripts
• DRY consolidation - Reduced duplicate patterns across workflows and actions
• Shell-free design - Moved inline shell commands to dedicated scripts
• Environment standardization - Consistent variable usage across all workflows
• Documentation restructure - Improved organization and navigation
• Enhanced tool analysis - Detailed comparisons with core tools

🤝 Contributing to Documentation

Found an issue with the documentation? Want to improve it?

1. Small fixes: Edit files directly and submit a PR
2. New content: Follow the Contributing Guide
3. Feedback: Open an issue with suggestions

Documentation Standards

• Clear headings with consistent hierarchy
• Code examples for all instructions
• Cross-references between related topics
• Up-to-date links and accurate information

---

Need help? Check the specific guide for your use case, or open an issue on GitHub if you can’t find what you’re looking for! 🚀