README.md

🚀 PyPage - Enhanced HTML Generator Library

Create stunning, responsive web pages with Python

PyPage is a comprehensive Python library that revolutionizes HTML generation with advanced features including dark mode, animations, responsive design, and modern UI components. Build professional websites programmatically with an intuitive, object-oriented approach.

🎯 Everything you need to create modern webpages programmatically

📚 Complete component reference with easy-to-use syntax

✨ Why Choose PyPage?

🎨 Modern & Beautiful Bootstrap 5 Integration - Professional styling out of the box Dark Mode Support - Automatic system preference detection Custom Themes - Material, Tailwind, Bulma support Responsive Design - Mobile-first approach	⚡ Fast & Powerful Component-Based - Reusable, modular architecture Type-Safe - Full type hints for better development Performance Optimized - WebAssembly integration Hot Reload - Development server with live updates
🛠️ Developer Friendly Intuitive API - Pythonic, object-oriented design Rich Documentation - Complete guides and examples CLI Tools - Project scaffolding and templates Flask Integration - Seamless web framework support	🚀 Production Ready Export Options - PDF, JSON, static HTML SEO Optimized - Built-in meta tags and structure Accessibility - WCAG compliance tools Plugin System - Extensible architecture

📦 Installation

# Basic installation
pip install pypage

# With PDF export support
pip install pypage[pdf]

# With chart support
pip install pypage[charts]

# Full installation with all features
pip install pypage[full]

🎯 Quick Start

from pypage import *

# Create a new page
page = Page("My Website", "Welcome to PyPage!")

# Add content
page.add_content(Heading("Hello, World!", 1))
page.add_content(Paragraph("Build amazing websites with Python."))

# Add a styled card
card = Card([
    Heading("Getting Started", 3),
    Paragraph("PyPage makes HTML generation simple and powerful."),
    Button("Learn More", "button", css_class="btn-primary")
])
page.add_content(card)

# Generate HTML
html = page.generate_html()
print(html)

🌟 Advanced Features

Dark Mode Support

page = Page("Dark Mode Demo", "Theme Switching")
page.add_content(DarkModeToggle(position="top-right"))
page.add_content(Heading("Dark Mode Ready!", 1))

Animations

# Fade in animation
animated_content = FadeIn(
    Container([
        Heading("Smooth Animations", 2),
        Paragraph("Content that fades in beautifully.")
    ])
)
page.add_content(animated_content)

Responsive Layout

row = Row()
row.add_column(Column([
    Heading("Left Column", 3),
    Paragraph("Responsive content here.")
], width="md-6"))
row.add_column(Column([
    Heading("Right Column", 3), 
    Paragraph("More responsive content.")
], width="md-6"))
page.add_content(row)

Data Visualization

# Create a chart
chart_data = {
    "labels": ["Jan", "Feb", "Mar", "Apr"],
    "datasets": [{
        "label": "Sales",
        "data": [10, 19, 3, 5]
    }]
}
chart = BarChart("sales-chart", chart_data)
page.add_content(chart)

🛠️ CLI Tools

PyPage includes command-line tools for project generation:

# Create a new project
pypage create myproject

# Create a Flask project
pypage create myapp --template flask

# Generate documentation
pypage docs

📚 Component Library

PyPage includes a comprehensive set of components:

Core Components

• Page - Main page container with theme support
• Container, Div, Section - Layout containers
• Heading, Paragraph - Typography elements
• Image, Link - Media and navigation
• Card - Content cards with styling

Form Components

• Form - Form container with validation
• Input - Text, email, password, and other input types
• TextArea - Multi-line text input
• Select - Dropdown with single/multiple selection
• Button - Submit and action buttons

Layout System

• Row, Column - Responsive grid system
• Flex - Flexbox layouts
• Navbar - Navigation with dropdown support

Advanced Components

• Modal, Alert, Badge - Interactive elements
• Table, Tabs, Carousel - Data display
• ProgressBar, Accordion - UI components
• Chart, KPICard - Data visualization

🎨 Styling and Themes

PyPage uses Bootstrap 5 by default with a custom dark theme:

# Set theme
page.set_theme('bootstrap')  # or 'material', 'tailwind'

# Custom CSS
css_builder = CSSBuilder()
css_builder.add_rule('.custom', {
    'background': 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    'color': 'white'
})
page.custom_css = css_builder.render()

🧪 Testing

The library includes a comprehensive testing application:

cd testing
python app.py

Visit http://localhost:5001 to run interactive tests and see component demonstrations.

📖 Documentation & Resources

📘 Core Documentation	🎯 Guides & Tutorials	🛠️ Development
🚀 Quick Start Get up and running in 5 minutes	🎨 Theme Customization Create beautiful custom themes	🔧 API Reference Complete component documentation
📦 Installation Guide Multiple installation options	📱 Responsive Design Mobile-first development	🧪 Testing Guide Test your components
🏗️ Architecture Understanding PyPage structure	🌙 Dark Mode Setup Implement dark mode support	🔌 Plugin Development Create custom components

📊 Visual Guides

Component Architecture - Complete system organization

Development Workflow - From installation to deployment

🎓 Learning Resources

Theme System - Beautiful, customizable themes for every project

• 📚 Component Gallery - Visual showcase of all components
• 💡 Examples Library - Real-world usage examples
• 🎮 Interactive Playground - Live testing environment
• 📺 Video Tutorials - Step-by-step video guides
• ❓ FAQ - Common questions and solutions
• 🎨 Theme Gallery - Beautiful theme customization examples

🤝 Contributing

We love contributions from the community! PyPage is built by developers, for developers.

🚀 Ways to Contribute

🐛 Bug Reports Found an issue? Report it! Include reproduction steps Provide system details Help make PyPage better	💡 Feature Requests Suggest new components Propose improvements Share your ideas Shape PyPage's future	📝 Documentation Improve guides Add examples Fix typos Help others learn
🔧 Code Contributions Fix bugs Add features Optimize performance Write tests	🎨 Themes & Examples Create beautiful themes Share real-world examples Build showcase projects Inspire others	💬 Community Support Answer questions Help newcomers Share knowledge Build community

📋 Quick Start for Contributors

# 1. Fork and clone the repository
git clone https://github.com/yourusername/pypage.git
cd pypage

# 2. Install development dependencies  
pip install -e .[dev]

# 3. Make your changes
# Edit code, add tests, update docs

# 4. Run tests and checks
pytest                    # Run test suite
black .                   # Format code
flake8 .                  # Check style
mypy src/pypage/          # Type checking

# 5. Submit your pull request
git commit -m "Add amazing feature"
git push origin feature-branch

🎯 Contribution Guidelines

• Follow the code style - We use Black and follow PEP 8
• Add tests - New features should include tests
• Update documentation - Keep docs current with changes
• Be respectful - Follow our code of conduct
• Start small - Begin with minor improvements or bug fixes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

• Bootstrap team for the excellent CSS framework
• Flask community for web framework inspiration
• All contributors who have helped improve PyPage

---

PyPage - Making HTML generation simple, powerful, and beautiful.