mkdocs.yml

site_name: lifx-async
site_description: A modern, type-safe, async Python library for controlling LIFX lights
site_author: Avi Miller <me@dje.li>
site_url: https://djelibeybi.github.io/lifx-async

repo_name: Djelibeybi/lifx-async
repo_url: https://github.com/Djelibeybi/lifx-async
edit_uri: edit/main/docs/

theme:
  name: material
  palette:
    # Light mode
  - scheme: default
    primary: indigo
    accent: blue
    toggle:
      icon: material/brightness-7
      name: Switch to dark mode
    # Dark mode
  - scheme: slate
    primary: indigo
    accent: blue
    toggle:
      icon: material/brightness-4
      name: Switch to light mode
  features:
  - navigation.tracking
  - navigation.tabs
  - navigation.tabs.sticky
  - navigation.sections
  - navigation.path
  - navigation.indexes
  - navigation.top
  - toc.follow
  - search.suggest
  - search.highlight
  - content.code.copy
  - content.code.annotate
  - content.tabs.link
  icon:
    repo: fontawesome/brands/github
    logo: material/lightbulb
  favicon: assets/favicon.png

plugins:
- search:
    lang: en
- mkdocstrings:
    handlers:
      python:
        paths: [src]    # Add source path for imports
          # Load object inventories to enable cross-references to other projects.
        inventories:
        - https://docs.python.org/3/objects.inv
        options:
          docstring_options:
            ignore_init_summary: true

            # Docstring parsing
          docstring_style: google
          docstring_section_style: spacy

            # Headings and structure
          show_root_heading: true
          show_root_full_path: false
          show_root_members_full_path: false
          show_object_full_path: false
          show_category_heading: true
          heading_level: 2

            # Signatures
          show_signature: true
          show_signature_annotations: true
          separate_signature: true
          signature_crossrefs: true

            # Members
          members_order: source
          group_by_category: true
          show_if_no_docstring: false
          show_docstring_attributes: true
          show_docstring_functions: true
          show_docstring_classes: true
          show_docstring_modules: true

            # Source code
          show_source: true

            # Inheritance
          show_bases: true
          show_inheritance_diagram: false

            # Special members
          merge_init_into_class: true
          show_labels: true

            # Additional improvements
          annotations_path: brief
          line_length: 80
          show_symbol_type_heading: true
          show_symbol_type_toc: true
          summary: true

- git-revision-date-localized:
    enable_creation_date: true

- llmstxt:
    markdown_description: |
      lifx-async is a modern, type-safe, async Python library for controlling LIFX smart devices
      over the local network. Built with Python's built-in asyncio for async/await patterns and
      features auto-generated protocol structures from a YAML specification.

      Key features:
      - Zero runtime dependencies
      - Full async/await support with asyncio
      - Type-safe with strict Pyright validation
      - Auto-generated protocol from official LIFX specification
      - Supports all LIFX device types: Light, HevLight, InfraredLight, MultiZoneLight, and TileDevice
      - High-level API with device discovery and batch operations
      - Concurrent request handling with connection pooling
    sections:
      Getting Started:
      - getting-started/installation.md: Installation instructions and requirements
      - getting-started/quickstart.md: Quick start guide with basic examples
      - getting-started/themes.md: Using predefined color themes
      - getting-started/effects.md: Light effects and animations
      User Guide:
      - user-guide/themes.md: Working with color themes
      - user-guide/ceiling-lights.md: Controlling LIFX Ceiling uplight and downlight components
      - user-guide/animation.md: High-frequency animation for real-time effects
      - user-guide/advanced-usage.md: Advanced usage patterns and best practices
      - user-guide/effects-custom.md: Creating custom light effects
      - user-guide/troubleshooting.md: Common issues and solutions
      - user-guide/effects-troubleshooting.md: Effects-specific troubleshooting
      - user-guide/protocol-deep-dive.md: Understanding the LIFX protocol
      Architecture:
      - architecture/overview.md: System architecture and design
      - architecture/effects-architecture.md: Effects system architecture
      API Reference:
      - api/index.md: API reference overview
      - api/high-level.md: High-level discovery and batch operations API
      - api/themes.md: Theme system API
      - api/effects.md: Effects API
      - api/animation.md: Animation module for high-frequency frame delivery
      - api/colors.md: Color utilities and HSBK conversion
      - api/devices.md: Device classes and capabilities
      - api/network.md: Network layer components
      - api/protocol.md: Protocol layer and packet structures
      - api/exceptions.md: Exception hierarchy
      Migration:
      - migration/effect-api-changes.md: Effect API breaking changes and migration guide
      Additional Resources:
      - faq.md: Frequently asked questions
      - changelog.md: Version history and release notes
    full_output: llms-full.txt

markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences:
    custom_fences:
    - name: mermaid
      class: mermaid
      format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.highlight:
    anchor_linenums: true
    line_spans: __span
    pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.tabbed:
    alternate_style: true
- pymdownx.tasklist:
    custom_checkbox: true
- attr_list
- md_in_html
- tables
- footnotes
- def_list
- pymdownx.emoji:
    emoji_index: !!python/name:material.extensions.emoji.twemoji
    emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.critic
- pymdownx.caret
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
- toc:
    permalink: true
    toc_depth: 3

nav:
- Home: index.md
- Getting Started:
  - Installation: getting-started/installation.md
  - Quick Start: getting-started/quickstart.md
  - Themes: getting-started/themes.md
  - Light Effects: getting-started/effects.md
- User Guide:
  - Themes: user-guide/themes.md
  - Ceiling Lights: user-guide/ceiling-lights.md
  - Animation: user-guide/animation.md
  - Advanced Usage: user-guide/advanced-usage.md
  - Custom Effects: user-guide/effects-custom.md
  - Troubleshooting: user-guide/troubleshooting.md
  - Effects Troubleshooting: user-guide/effects-troubleshooting.md
  - Protocol Deep Dive: user-guide/protocol-deep-dive.md
- Architecture:
  - Overview: architecture/overview.md
  - Effects System: architecture/effects-architecture.md
- API Reference:
  - Overview: api/index.md
  - High-Level API: api/high-level.md
  - Themes: api/themes.md
  - Effects: api/effects.md
  - Animation: api/animation.md
  - Color Utilities: api/colors.md
  - Device Classes: api/devices.md
  - Network Layer: api/network.md
  - Protocol Layer: api/protocol.md
  - Exceptions: api/exceptions.md
- Migration:
  - Effect API Changes: migration/effect-api-changes.md
- FAQ: faq.md
- Changelog: changelog.md

extra:
  social:
  - icon: fontawesome/brands/github
    link: https://github.com/Djelibeybi/lifx-async
  - icon: fontawesome/brands/python
    link: https://pypi.org/project/lifx-async/
  version:
    provider: mike

extra_css:
- stylesheets/extra.css

copyright: Copyright &copy; 2025 Avi Miller