🚀 Quick Start Guide
==================

{{ description | default("Get up and running with " + project_display_name + " in under 5 minutes!") }}

.. admonition:: Prerequisites
   :class: note
   
   {% if prerequisites %}{{ prerequisites }}{% else %}
   - **Python 3.8+** 
   - **pip** or **Poetry** package manager
   - Basic familiarity with Python
   {% endif %}

Installation
============

.. tab-set::

   .. tab-item:: 📦 Using pip

      .. code-block:: bash
         
         # Install the latest version
         pip install {{ package_name }}
         
         # Verify installation
         python -c "import {{ import_name | default(package_name.replace('-', '_')) }}; print('✅ Installation successful!')"

   .. tab-item:: 📝 Using Poetry

      .. code-block:: bash
         
         # Add to your project
         poetry add {{ package_name }}
         
         # Or for development dependencies
         poetry add --group dev {{ package_name }}

   .. tab-item:: 🛠️ Development Setup

      .. code-block:: bash
         
         # Clone the repository
         git clone {{ repository_url | default("https://github.com/your-org/" + package_name) }}
         cd {{ package_name }}
         
         # Install with development dependencies
         poetry install --with dev
         
         # Run tests to verify setup
         poetry run pytest

{% if basic_usage %}
Basic Usage
===========

{{ basic_usage }}
{% else %}
Basic Usage
===========

Here's how to get started with {{ project_display_name }}:

.. dropdown:: 🎯 Hello World Example
   :color: primary
   :icon: code

   The simplest way to use {{ project_display_name }}:
   
   .. code-block:: python
      
      from {{ import_name | default(package_name.replace('-', '_')) }} import {{ main_class | default("main") }}
      
      # Create instance
      instance = {{ main_class | default("main") }}()
      
      # Basic usage
      result = instance.run("Hello, World!")
      print(result)

.. dropdown:: ⚙️ Configuration Example
   :color: success
   :icon: gear

   Customize behavior with configuration:
   
   .. code-block:: python
      
      from {{ import_name | default(package_name.replace('-', '_')) }} import {{ main_class | default("main") }}, Config
      
      # Create custom configuration
      config = Config(
          option1="custom_value",
          option2=True,
          option3=42
      )
      
      # Use with configuration
      instance = {{ main_class | default("main") }}(config=config)
      result = instance.run("Custom configuration example")

.. dropdown:: 🔧 Advanced Usage
   :color: warning
   :icon: tools

   For more complex scenarios:
   
   .. code-block:: python
      
      from {{ import_name | default(package_name.replace('-', '_')) }} import {{ main_class | default("main") }}, AsyncClient
      import asyncio
      
      async def advanced_example():
          # Async usage
          async with AsyncClient() as client:
              result = await client.process("Advanced example")
              return result
      
      # Run async example
      result = asyncio.run(advanced_example())
      print(f"Advanced result: {result}")
{% endif %}

{% if common_patterns %}
Common Patterns
===============

{{ common_patterns }}
{% else %}
Common Patterns
===============

.. grid:: 2
   :gutter: 3

   .. grid-item-card:: 🔄 Batch Processing
      :class-card: sd-border-primary
      
      Process multiple items efficiently:
      
      .. code-block:: python
         
         items = ["item1", "item2", "item3"]
         results = instance.batch_process(items)

   .. grid-item-card:: 🎛️ Custom Configuration  
      :class-card: sd-border-success
      
      Tailor behavior to your needs:
      
      .. code-block:: python
         
         config = Config.from_file("config.yaml")
         instance = {{ main_class | default("main") }}(config)
         
   .. grid-item-card:: 🔌 Plugin System
      :class-card: sd-border-warning
      
      Extend functionality with plugins:
      
      .. code-block:: python
         
         from {{ import_name | default(package_name.replace('-', '_')) }}.plugins import MyPlugin
         instance.add_plugin(MyPlugin())

   .. grid-item-card:: 📊 Monitoring & Logging
      :class-card: sd-border-danger
      
      Track performance and debug issues:
      
      .. code-block:: python
         
         import logging
         logging.basicConfig(level=logging.DEBUG)
         result = instance.run("Debug example")
{% endif %}

Next Steps
==========

.. grid:: 1 2 2 3
   :gutter: 2

   .. grid-item-card:: :octicon:`book` Examples
      :link: examples/index
      :link-type: doc
      :class-card: sd-text-center
      
      Explore detailed examples and tutorials

   .. grid-item-card:: :octicon:`gear` Configuration
      :link: configuration
      :link-type: doc
      :class-card: sd-text-center
      
      Learn about all configuration options
      
   .. grid-item-card:: :octicon:`code` API Reference
      :link: autoapi/index
      :link-type: doc
      :class-card: sd-text-center
      
      Browse the complete API documentation

Troubleshooting
===============

.. admonition:: Common Issues
   :class: tip
   
   {% if troubleshooting_tips %}{{ troubleshooting_tips }}{% else %}
   **Import Errors**: Make sure {{ package_name }} is installed in your current environment
   
   **Version Conflicts**: Use `pip list | grep {{ package_name }}` to check your installed version
   
   **Permission Issues**: Try installing with `pip install --user {{ package_name }}`
   {% endif %}

.. dropdown:: 🐛 Getting Help
   :color: info
   :icon: question

   If you're still having trouble:
   
   1. **Check the documentation** - Most questions are answered in the examples
   2. **Search existing issues** - {{ issues_url | default("https://github.com/your-org/" + package_name + "/issues") }}
   3. **Ask the community** - {{ community_url | default("Join our Discord/Slack") }}
   4. **File a bug report** - Include your Python version, OS, and a minimal example

.. dropdown:: 📝 Contributing
   :color: success  
   :icon: heart

   Want to help improve {{ project_display_name }}?
   
   - **Report bugs** and suggest features
   - **Improve documentation** with better examples
   - **Submit pull requests** with bug fixes or new features
   - **Help others** in the community forums
   
   See our [Contributing Guide](contributing.html) for more details!

Support
=======

.. tab-set::

   .. tab-item:: 📖 Documentation

      - **Examples**: Step-by-step tutorials
      - **API Reference**: Complete function/class documentation  
      - **Configuration**: All available options
      - **Troubleshooting**: Common issues and solutions

   .. tab-item:: 👥 Community

      - **GitHub Discussions**: {{ repository_url | default("https://github.com/your-org/" + package_name) }}/discussions
      - **Issue Tracker**: {{ issues_url | default("https://github.com/your-org/" + package_name + "/issues") }}
      {% if community_url %}- **Community Chat**: {{ community_url }}{% endif %}

   .. tab-item:: 🔧 Professional

      {% if support_contact %}{{ support_contact }}{% else %}
      For commercial support, consulting, or custom development:
      
      - Email: support@yourcompany.com
      - Professional services available
      - Custom integrations and features
      {% endif %}