🚀 dart_doc_pilot #

A powerful, feature-rich Flutter project documentation generator with a beautiful UI and impressive CLI experience.

dart_doc_pilot extracts comprehensive documentation from your Dart/Flutter projects and generates beautiful, searchable documentation in multiple formats.

✨ Features #

📚 Comprehensive Documentation Extraction #

• Classes: Full class documentation with inheritance, mixins, and interfaces
• Methods: All methods including getters, setters, async, static, and abstract
• Fields: Properties with type information, modifiers, and default values
• Constructors: Default, named, const, and factory constructors
• Enums: Enum declarations with value documentation
• Extensions: Extension methods and properties
• Typedefs: Type aliases with full context
• Parameters: Complete parameter information with types, defaults, and nullability

📝 Flutter Documentation Syntax Support #

Full support for Flutter-style documentation tags:

/// {@category Widgets}
/// {@subCategory Buttons}
/// 
/// {@template button_example}
/// Example usage...
/// {@endtemplate}
/// 
/// {@macro button_example}
/// 
/// See also: [TextButton], [IconButton]

🎨 Rich Output Formats #

• HTML: Beautiful, Material Design-inspired static website
• Markdown: Clean, readable documentation files
• JSON: Structured data for custom integrations

💎 Beautiful UI Features #

• 🔍 Live Search: Instant search with suggestions
• 📂 Category Navigation: Organized by categories and subcategories
• 🎯 Breadcrumb Navigation: Easy navigation hierarchy
• 💅 Syntax Highlighting: Beautiful code blocks
• 📱 Responsive Design: Works on all screen sizes
• ✨ Smooth Animations: Polished user experience

🖥️ Impressive CLI Experience #

• 🎨 ASCII Banner: Beautiful startup screen
• ⏳ Loading Animations: Spinners and progress bars
• 📊 Statistics: Detailed parsing and generation stats
• ⚡ Fast Performance: Optimized for large projects
• 🎭 Colored Output: Easy-to-read terminal output
• ✅ Success/Error Icons: Clear visual feedback

📦 Installation #

Global Installation #

dart pub global activate dart_doc_pilot

Project Dependency #

dev_dependencies:
  dart_doc_pilot: ^1.0.0

🚀 Quick Start #

1. Scan Your Project #

dart_doc_pilot scan ./my_flutter_app

Output:

╔═══════════════════════════════════════════════════════════════╗
║                     🚀 Flutter Documentation Generator 🚀      ║
╚═══════════════════════════════════════════════════════════════╝

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Scanning Project
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📂 Directory: /path/to/my_flutter_app

🔎 Discovering Dart files... ✓
📖 Parsing documentation... ✓

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✨ Scan Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📦 Classes           42
  🔢 Enums             8
  🔧 Extensions        5
  📝 Typedefs          3
  ⚡ Methods           156
  💎 Fields            89
  🏗️  Constructors      67

⏱️  Completed in 234ms
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2. Generate Documentation #

HTML (Recommended)

dart_doc_pilot build ./my_flutter_app --format html --output docs

Markdown

dart_doc_pilot build ./my_flutter_app --format markdown --output md_docs

JSON

dart_doc_pilot build ./my_flutter_app --format json --output api_docs

3. Serve Documentation #

dart_doc_pilot serve ./my_flutter_app --port 8080

Then open: http://localhost:8080

📖 Documentation Features #

Class Documentation #

/// A custom button widget with various styles.
/// 
/// {@category Widgets}
/// {@subCategory Buttons}
/// 
/// The [CustomButton] provides a flexible button implementation.
/// 
/// Example:
/// ```dart
/// CustomButton(
///   text: 'Click Me',
///   onPressed: () => print('Pressed!'),
/// );
/// ```
class CustomButton {
  // ...
}

Extracted Information:

• ✅ Description
• ✅ Category & Subcategory
• ✅ Code examples
• ✅ Cross-references ([CustomButton])
• ✅ Inheritance tree
• ✅ All members (fields, methods, constructors)

Method Documentation #

/// Handles user login with email and password.
/// 
/// Returns a [User] object on success.
/// Throws [AuthException] on failure.
/// 
/// Example:
/// ```dart
/// final user = await login(
///   email: '[email protected]',
///   password: 'password',
/// );
/// ```
Future<User> login({
  required String email,
  required String password,
}) async {
  // ...
}

Extracted Information:

• ✅ Description
• ✅ Return type (Future
• ✅ Parameters with types
• ✅ Required/optional status
• ✅ Async/await support
• ✅ Code examples
• ✅ Exception documentation

🎯 CLI Commands #

scan #

Scan and analyze Dart files in a project.

dart_doc_pilot scan <directory>

Options:

• None

Example:

dart_doc_pilot scan ./my_app

build #

Generate documentation in specified format.

dart_doc_pilot build <directory> [options]

Options:

• -f, --format - Output format: html, markdown, json (default: html)
• -o, --output - Output directory (default: docs)

Examples:

# HTML documentation
dart_doc_pilot build ./my_app -f html -o docs

# Markdown documentation
dart_doc_pilot build ./my_app -f markdown -o md_docs

# JSON export
dart_doc_pilot build ./my_app -f json -o api.json

serve #

Start a local documentation server.

dart_doc_pilot serve <directory> [options]

Options:

• -p, --port - Server port (default: 8080)

Example:

dart_doc_pilot serve ./my_app --port 3000

🏗️ Project Structure #

dart_doc_pilot/
├── bin/
│   └── dart_doc_pilot.dart      # CLI entry point
├── lib/
│   ├── models.dart               # Data models
│   ├── parser.dart               # Documentation parser
│   ├── exporters.dart            # Output generators
│   ├── cli.dart                  # CLI interface
│   └── dart_doc_pilot.dart       # Library exports
├── example/
│   └── lib/
│       ├── custom_button.dart    # Example file
│       └── auth_service.dart     # Example file
├── pubspec.yaml
└── README.md

🎨 HTML Output Features #

The generated HTML documentation includes:

Navigation #

• Sidebar: Organized by categories
• Search Bar: Live filtering
• Breadcrumbs: Clear hierarchy

Content Display #

• Class Overview: Description, inheritance, members
• Method Signatures: Syntax-highlighted code blocks
• Parameter Lists: Detailed parameter information
• Code Examples: Formatted with syntax highlighting

Design #

• Material Design 3: Modern, clean aesthetic
• Responsive Layout: Mobile-friendly
• Dark/Light Support: System preference detection
• Smooth Animations: Polished interactions

🔧 Advanced Usage #

Programmatic API #

import 'package:dart_doc_pilot/dart_doc_pilot.dart';

void main() async {
  // Parse documentation
  final parser = DartDocParser(rootPath: './my_app');
  final documentation = await parser.parse();
  
  // Export to HTML
  final htmlExporter = HtmlExporter();
  await htmlExporter.export(documentation, './docs');
  
  // Export to JSON
  final jsonExporter = JsonExporter();
  await jsonExporter.export(documentation, './api.json');
  
  // Export to Markdown
  final mdExporter = MarkdownExporter();
  await mdExporter.export(documentation, './md_docs');
}

Custom Exclusions #

final parser = DartDocParser(
  rootPath: './my_app',
  excludePaths: ['build', '.dart_tool', 'test', 'generated'],
);

📊 Supported Documentation Tags #

🎯 Use Cases #

• 📚 Public Packages: Generate beautiful API documentation
• 👥 Team Projects: Share consistent documentation
• 📖 Open Source: Professional documentation sites
• 🏢 Enterprise: Internal API documentation
• 🎓 Education: Teaching materials with examples

🔮 Roadmap #

• ❌ Custom themes for HTML output
• ❌ PDF export support
• ❌ Dark mode toggle in UI
• ❌ Search result highlighting
• ❌ API documentation versioning
• ❌ Diagram generation (class hierarchy)
• ❌ Multi-language support
• ❌ IDE plugins (VS Code, IntelliJ)

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License #

This project is licensed under the MIT License.

🌟 Acknowledgments #

• Inspired by Flutter.dev documentation
• Built with the Dart analyzer package
• UI design influenced by Material Design 3
• CLI experience powered by mason_logger

📞 Support #

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

Made with ❤️ by the Flutter community