# milsat_modules_flutter Documentation

Welcome to the comprehensive documentation for the **milsat_modules_flutter** package!

## 📚 Documentation Files

This directory contains:

1. **`index.html`** - Interactive HTML documentation website
2. **`css/`** - Stylesheets for the documentation
   - `main.css` - Core styles, layout, and components
   - `prism.css` - Code syntax highlighting theme
   - `print.css` - Print/PDF optimization styles
3. **`js/`** - JavaScript files for interactivity
   - `main.js` - Navigation, search, and interactive features
   - `prism.js` - Syntax highlighting for Dart, YAML, and JSON

## 🌐 Viewing the HTML Documentation

### Option 1: Open Directly in Browser (Recommended)

Simply double-click `index.html` or open it in your preferred browser:

```bash
# macOS
open index.html

# Linux
xdg-open index.html

# Windows
start index.html
```

### Option 2: Serve with Local Web Server

For better performance with some browsers:

```bash
# Python 3
python3 -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

# Node.js (if you have npx)
npx serve .
```

Then visit: `http://localhost:8000`

## 📄 Generating PDF Documentation

### Method 1: Browser Print-to-PDF (Easiest)

1. Open `index.html` in your browser
2. Press `Ctrl+P` (Windows/Linux) or `Cmd+P` (macOS) to open print dialog
3. Select **"Save as PDF"** or **"Microsoft Print to PDF"** as the destination
4. **Important PDF Settings:**
   - **Layout:** Portrait
   - **Paper size:** A4 or Letter
   - **Margins:** Default or Custom (0.5in recommended)
   - **Options:**
     - ✅ Background graphics (to preserve code block styling)
     - ✅ Headers and footers (optional)
5. Click **"Save"** or **"Print"**
6. Save as `milsat_modules_flutter_documentation.pdf`

**Recommended Browsers for PDF Generation:**
- **Google Chrome/Chromium** - Best quality
- **Microsoft Edge** - Excellent PDF output
- **Safari** - Good for macOS users
- **Firefox** - Works well but may have minor styling differences

### Method 2: Automated PDF Generation (Advanced)

If you have Node.js installed, you can use Puppeteer for automated PDF generation:

```bash
# Install Puppeteer
npm install -g puppeteer

# Create a PDF generation script
cat > generate-pdf.js << 'EOF'
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.goto('file://' + __dirname + '/index.html', {
    waitUntil: 'networkidle0'
  });

  await page.pdf({
    path: 'milsat_modules_flutter_documentation.pdf',
    format: 'A4',
    margin: {
      top: '1.5cm',
      right: '1.5cm',
      bottom: '2cm',
      left: '1.5cm'
    },
    printBackground: true,
    preferCSSPageSize: true
  });

  await browser.close();
  console.log('PDF generated successfully!');
})();
EOF

# Run the script
node generate-pdf.js
```

### Method 3: Online PDF Converter

1. Upload `index.html` to an online HTML-to-PDF converter:
   - https://www.html-to-pdf.net/
   - https://www.sejda.com/html-to-pdf
   - https://cloudconvert.com/html-to-pdf
2. Download the generated PDF

## 📋 Documentation Sections

The documentation covers:

1. **Introduction** - Package overview, features, architecture
2. **Getting Started** - Installation, quick start, basic setup
3. **Common Module** - Foundation, error handling, networking
4. **User Module** - Authentication, user management
5. **Form Module** - Dynamic form builder, widgets, validation
6. **Data Module** - CRUD operations, export, sync
7. **Location Module** - Hierarchical location services
8. **Map Module** - Mapbox integration, geometry drawing
9. **Best Practices** - Recommended patterns, gotchas
10. **API Reference** - Complete API tables, troubleshooting

## ✨ Features

### Interactive HTML Documentation
- ✅ **Dark/Light mode toggle** - Switch between themes with one click
- ✅ Responsive design (mobile, tablet, desktop)
- ✅ Syntax-highlighted code examples (Dart, YAML, JSON)
- ✅ Copy-to-clipboard buttons on all code blocks
- ✅ Search functionality
- ✅ Smooth navigation with active section highlighting
- ✅ Mobile-friendly sidebar menu
- ✅ Back-to-top button
- ✅ Print-optimized CSS
- ✅ Theme preference saved in browser

### Code Examples
- Real-world usage patterns from the test app
- Complete examples for all major features
- Best practices and anti-patterns
- Error handling demonstrations

## 🎨 Customization

### Modifying Styles

Edit `css/main.css` to customize:
- Colors (see CSS variables at the top)
- Typography
- Layout and spacing
- Component styles

### Changing Code Theme

Edit `css/prism.css` to modify the syntax highlighting theme.

### Adding Content

The HTML is well-structured with semantic sections. To add content:
1. Add a new `<section id="your-section">` in `index.html`
2. Add a navigation link in the sidebar
3. Update the table of contents if needed

## 📏 Documentation Stats

- **Total Lines:** ~1,600 lines of HTML
- **Sections:** 10 major sections
- **Code Examples:** 40+ real-world examples
- **Tables:** 10+ reference tables
- **Estimated PDF Pages:** 80-100 pages
- **CSS Lines:** ~1,500 lines
- **JavaScript Lines:** ~500 lines

## 🔧 Troubleshooting

### HTML not displaying properly
- Ensure all CSS and JS files are in the correct directories
- Check browser console for errors (F12)
- Try a different browser

### Code highlighting not working
- Ensure `js/prism.js` is loaded
- Check that code blocks have the correct `language-dart` class

### Search not working
- Ensure `js/main.js` is loaded
- Check browser console for JavaScript errors

### PDF looks different from HTML
- Ensure "Background graphics" is enabled in print settings
- Try Chrome/Edge for better PDF output quality
- Use the print.css media query for PDF-specific adjustments

## 📞 Support

For issues or questions:
- GitHub Issues: https://github.com/HaywhyD/milsat_modules_flutter/issues
- Package Repository: https://github.com/HaywhyD/milsat_modules_flutter

## 📄 License

This documentation is part of the milsat_modules_flutter package.
See LICENSE file for details.

---

**Generated:** 2025-11-28
**Package Version:** 1.3.0
**Documentation Version:** 1.0.0
