ruff-sync 0.1.0.dev0__tar.gz → 0.1.0.dev2__tar.gz

ruff_sync-0.1.0.dev2/.agents/skills/mkdocs-generation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: mkdocs-generation
+description: Generate MkDocs documentation sites with Material theme, mkdocstrings for API docs, and versioning. Use when setting up or extending project documentation.
+---
+
+# MkDocs Documentation Generation
+
+Generate professional documentation sites using MkDocs Material theme with automatic API reference generation.
+
+## Stack
+
+- **MkDocs**: Static site generator for project documentation
+- **Material Theme**: Modern, responsive theme with navigation features
+- **mkdocstrings**: Auto-generate API docs from Python docstrings
+- **mike**: Version management for documentation
+
+## Dependencies
+
+Add to `pyproject.toml` (optional extras group):
+
+```toml
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.4",
+    "mkdocstrings[python]>=0.24",
+    "mike>=2.0",
+]
+```
+
+Or `requirements.txt`:
+
+```
+mkdocs>=1.5
+mkdocs-material>=9.4
+mkdocstrings[python]>=0.24
+mike>=2.0
+```
+
+## Directory Structure
+
+**Simple (flat)**:
+```
+docs/
+├── index.md           # Home/overview
+├── getting-started.md # Installation and quickstart
+├── configuration.md   # Config options
+└── tools.md          # Feature reference
+```
+
+**Complex (nested)**:
+```
+docs/
+├── index.md
+├── compatibility.md
+├── guide/
+│   ├── getting-started.md
+│   ├── cli.md
+│   └── advanced.md
+└── api/
+    ├── panel.md       # ::: module.Class
+    └── entities/
+        ├── area.md
+        └── zone.md
+```
+
+## mkdocs.yml Configuration
+
+See `templates/mkdocs.yml` for the full configuration template.
+
+Key sections:
+1. **Site metadata**: name, description, URLs
+2. **Versioning**: mike provider for multi-version docs
+3. **Theme**: Material with navigation features
+4. **Plugins**: search + mkdocstrings for API docs
+5. **Navigation**: Explicit nav structure
+
+## API Reference with mkdocstrings
+
+Create minimal markdown files that reference Python modules:
+
+```markdown
+# Panel API
+
+::: mypackage.panel.Panel
+
+::: mypackage.panel.PanelSync
+```
+
+mkdocstrings auto-generates documentation from docstrings. Configure in `mkdocs.yml`:
+- `docstring_style: google` - Use Google-style docstrings
+- `show_source: false` - Hide source code
+- `merge_init_into_class: true` - Combine `__init__` with class docs
+- `filters: ["!^_"]` - Exclude private members
+
+## Commands
+
+```bash
+# Serve locally with hot-reload
+mkdocs serve
+
+# Build static site
+mkdocs build
+
+# Deploy to GitHub Pages
+mkdocs gh-deploy
+
+# Version management (mike)
+mike deploy --push --update-aliases 0.1.0 latest
+mike set-default --push latest
+```
+
+## Writing Guidelines
+
+1. **index.md**: Brief overview, key features as bullet list, installation snippet, "Where to Next" links
+2. **getting-started.md**: Prerequisites, step-by-step setup, minimal working example
+3. **API docs**: Let mkdocstrings generate from docstrings; add brief intro if needed
+4. **Guides**: Task-oriented, include code examples, link to related API docs
+
+## Templates
+
+- `templates/mkdocs.yml` - Configuration file
+- `templates/index.md` - Home page
+- `templates/getting-started.md` - Quickstart guide
+- `templates/api-reference.md` - API doc page using mkdocstrings

ruff_sync-0.1.0.dev2/.agents/skills/mkdocs-generation/examples.md

@@ -0,0 +1,223 @@
+# MkDocs Generation Examples
+
+Real-world patterns from todoist-mcp and pydmp repositories.
+
+## Simple Documentation (todoist-mcp)
+
+Flat structure for smaller projects:
+
+```
+docs/
+├── index.md
+├── getting-started.md
+├── configuration.md
+└── tools.md
+```
+
+**mkdocs.yml nav:**
+```yaml
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md
+  - MCP Tools: tools.md
+```
+
+**index.md:**
+```markdown
+# Todoist MCP Server
+
+The Todoist MCP server is a Model Context Protocol (MCP) server for managing Todoist tasks from MCP clients like Claude Desktop.
+
+Use this documentation to:
+
+- Learn what the server can do
+- Set up Docker-based or local development environments
+- Configure environment variables and Redis caching
+- Explore the available MCP tools for task and project management
+```
+
+## Complex Documentation (pydmp)
+
+Nested structure for larger projects with API reference:
+
+```
+docs/
+├── index.md
+├── compatibility.md
+├── guide/
+│   ├── getting-started.md
+│   ├── cli.md
+│   ├── realtime-status.md
+│   ├── encryption.md
+│   └── migration.md
+└── api/
+    ├── panel.md
+    ├── protocol.md
+    ├── status.md
+    ├── entities/
+    │   ├── area.md
+    │   ├── zone.md
+    │   ├── output.md
+    │   ├── user.md
+    │   └── profile.md
+    └── protocol/
+        └── encryption.md
+```
+
+**mkdocs.yml nav:**
+```yaml
+nav:
+  - Home: index.md
+  - Panel Compatibility: compatibility.md
+  - Guide:
+      - Getting Started: guide/getting-started.md
+      - CLI: guide/cli.md
+      - Realtime Status (S3): guide/realtime-status.md
+      - Encryption & User Data: guide/encryption.md
+      - Migration: guide/migration.md
+  - API Reference:
+      - Panel: api/panel.md
+      - Entities:
+          - Area: api/entities/area.md
+          - Zone: api/entities/zone.md
+          - Output: api/entities/output.md
+          - User Code: api/entities/user.md
+          - User Profile: api/entities/profile.md
+      - Protocol:
+          - Protocol: api/protocol.md
+          - Encryption: api/protocol/encryption.md
+      - Realtime Server: api/status.md
+```
+
+## Index Page with Code Examples
+
+```markdown
+# PyDMP
+
+PyDMP is a platform-agnostic Python library for controlling DMP alarm panels.
+
+**Key Features:**
+
+- **Dual APIs**: Choose async for modern applications or sync for simple scripts
+- **High-level abstractions**: Work with panels, areas, zones, and outputs
+- **Built-in rate limiting**: Automatic command throttling
+
+## Installation
+
+\`\`\`bash
+pip install pydmp
+\`\`\`
+
+## Quick Start (Async)
+
+\`\`\`python
+import asyncio
+from pydmp import DMPPanel
+
+async def main():
+    panel = DMPPanel()
+    await panel.connect("192.168.1.100", "00001", "YOURKEY")
+    await panel.update_status()
+    areas = await panel.get_areas()
+    await panel.disconnect()
+
+asyncio.run(main())
+\`\`\`
+
+## Where to Next
+
+- [Getting Started](guide/getting-started.md) - Installation and connection
+- [CLI Guide](guide/cli.md) - Command-line interface
+- [API Reference](api/panel.md) - Complete API documentation
+```
+
+## API Reference Page (mkdocstrings)
+
+Minimal markdown that generates full API docs:
+
+```markdown
+# Panel API
+
+::: pydmp.panel.DMPPanel
+
+::: pydmp.panel_sync.DMPPanelSync
+```
+
+For entity docs:
+
+```markdown
+# Area
+
+::: pydmp.area.Area
+
+::: pydmp.area.AreaSync
+```
+
+## CLI Documentation Pattern
+
+```markdown
+# Command-Line Interface (CLI)
+
+PyDMP ships with a CLI for common operations.
+
+## Installation
+
+\`\`\`bash
+pip install pydmp[cli]
+\`\`\`
+
+## Configuration
+
+The CLI expects a YAML config file:
+
+\`\`\`yaml
+panel:
+  host: 192.168.1.100
+  account: "00001"
+  remote_key: "YOURKEY"
+\`\`\`
+
+## Commands
+
+### Areas & Zones
+\`\`\`bash
+pydmp get-areas [--json|-j]
+pydmp get-zones [--json|-j]
+\`\`\`
+
+### Arm/Disarm
+\`\`\`bash
+pydmp arm "1,2,3" [--bypass-faulted|-b] [--force-arm|-f]
+pydmp disarm <AREA> [--json|-j]
+\`\`\`
+
+## Examples
+
+\`\`\`bash
+# View areas with debug logs
+pydmp --debug get-areas
+
+# Arm area 1
+pydmp arm "1" --bypass-faulted
+\`\`\`
+```
+
+## pyproject.toml Integration
+
+```toml
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.4",
+    "mkdocstrings[python]>=0.24",
+    "mike>=2.0",
+]
+```
+
+Install and build:
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+mkdocs build
+```

ruff_sync-0.1.0.dev2/.agents/skills/mkdocs-generation/templates/api-reference.md

@@ -0,0 +1,33 @@
+# API Reference
+
+<!--
+mkdocstrings generates API documentation from Python docstrings.
+Use the ::: directive to include a module, class, or function.
+
+Syntax:
+::: package.module.ClassName
+::: package.module.function_name
+
+The plugin reads docstrings and type hints to generate documentation.
+Use Google-style docstrings for best results.
+-->
+
+## [MainClass]
+
+::: [package].[module].[MainClass]
+
+## [SecondaryClass]
+
+::: [package].[module].[SecondaryClass]
+
+<!--
+For nested API structure, create subdirectories:
+
+docs/api/
+├── index.md      - API overview
+├── client.md     - ::: package.client.Client
+├── models.md     - ::: package.models
+└── entities/
+    ├── user.md   - ::: package.entities.User
+    └── item.md   - ::: package.entities.Item
+-->

ruff_sync-0.1.0.dev2/.agents/skills/mkdocs-generation/templates/getting-started.md

@@ -0,0 +1,46 @@
+# Getting Started
+
+This guide walks through [what the guide covers].
+
+## Prerequisites
+
+- Python 3.9+
+- [Other prerequisites]
+
+## Installation
+
+```bash
+pip install [package-name]
+```
+
+## Configuration
+
+[Explain any required configuration, environment variables, or config files.]
+
+```bash
+# Example: copy and edit config
+cp config.example.yaml config.yaml
+```
+
+## Basic Usage
+
+### [First Concept/Task]
+
+```python
+from [package] import [Class]
+
+# Example code
+obj = [Class]()
+result = obj.method()
+```
+
+### [Second Concept/Task]
+
+```python
+# Example code for second task
+```
+
+## Next Steps
+
+- [Configuration](configuration.md) - Advanced configuration options
+- [API Reference](api.md) - Full API documentation

ruff_sync-0.1.0.dev2/.agents/skills/mkdocs-generation/templates/index.md

@@ -0,0 +1,32 @@
+# [PROJECT_NAME]
+
+[One-sentence description of what this project does and who it's for.]
+
+**Key Features:**
+
+- **[Feature 1]**: [Brief description]
+- **[Feature 2]**: [Brief description]
+- **[Feature 3]**: [Brief description]
+
+## Installation
+
+```bash
+pip install [package-name]
+```
+
+## Quick Start
+
+```python
+from [package] import [MainClass]
+
+# Minimal working example
+client = [MainClass]()
+result = client.do_something()
+print(result)
+```
+
+## Where to Next
+
+- [Getting Started](getting-started.md) - Installation and setup walkthrough
+- [Configuration](configuration.md) - Configuration options
+- [API Reference](api.md) - Complete API documentation

ruff_sync-0.1.0.dev2/.agents/skills/mkdocs-generation/templates/mkdocs.yml

@@ -0,0 +1,59 @@
+# MkDocs Configuration Template
+# Replace placeholders: [SITE_NAME], [DESCRIPTION], [GITHUB_USER], [REPO_NAME], [PACKAGE_NAME]
+
+site_name: [SITE_NAME]
+site_description: [DESCRIPTION]
+site_url: https://[GITHUB_USER].github.io/[REPO_NAME]/
+repo_url: https://github.com/[GITHUB_USER]/[REPO_NAME]
+repo_name: [GITHUB_USER]/[REPO_NAME]
+
+extra:
+  version:
+    provider: mike
+    default: latest
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: false
+            members_order: source
+            show_if_no_docstring: true
+            show_signature_annotations: true
+            separate_signature: true
+            merge_init_into_class: true
+            show_root_heading: true
+            show_root_full_path: false
+            filters:
+              - "!^_"  # Exclude private members
+
+# Simple navigation (flat structure)
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Configuration: configuration.md
+  - API Reference: api.md
+
+# Complex navigation example (nested structure)
+# nav:
+#   - Home: index.md
+#   - Guide:
+#       - Getting Started: guide/getting-started.md
+#       - CLI: guide/cli.md
+#       - Advanced: guide/advanced.md
+#   - API Reference:
+#       - Overview: api/index.md
+#       - Core:
+#           - Client: api/client.md
+#           - Models: api/models.md

ruff_sync-0.1.0.dev2/.agents/skills/release-notes-generation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: release-notes-generation
+description: Draft professional and categorized release notes for ruff-sync using GitHub CLI, git history, and the `invoke release` task.
+---
+
+# Release Notes Generation
+
+This skill guides you through drafting high-quality release notes for `ruff-sync`. It leverages the `invoke release` task and GitHub CLI for context.
+
+## Prerequisites
+
+- **GitHub CLI (`gh`)**: Must be authenticated.
+- **Invoke**: Dev tasks are defined in `tasks.py`.
+- **Git**: Recent history and tags must be available.
+
+## Workflow
+
+### 1. Gather Context
+
+Before drafting, understand what has changed since the last release.
+
+```bash
+# Get the latest release tag and notes
+gh release list --limit 1
+gh release view <tag>
+
+# List merged PRs since the last tag
+# Replace <tag> with the tag found above
+gh pr list --state merged --search "merged:><tag-date>"
+
+# Or simple git log
+git log <tag>..HEAD --oneline
+```
+
+### 2. Create Draft Release
+
+Use the project's built-in release task to scaffold the release. This task automatically tags the release based on the version in `pyproject.toml` and uses GitHub's `--generate-notes` feature to create a starting point.
+
+```bash
+# Create a draft release (default behavior of invoke release)
+uv run invoke release --draft --skip-tests
+```
+
+> [!NOTE]
+> `invoke release` will:
+> 1. Check if you are on `main`.
+> 2. Check for clean git state.
+> 3. Create a GitHub Release with `--generate-notes`.
+
+### 3. Refine Release Notes
+
+GitHub's automatically generated notes are a good start but often lack professional categorization and narrative. Use the following structure for final refinement:
+
+#### Categorization
+- **🚀 Features**: New capabilities added to `ruff_sync`.
+- **🐞 Bug Fixes**: Issues resolved in CLI, merging logic, or HTTP handling.
+- **✨ Improvements**: Enhancements to existing features, performance, or logging.
+- **📖 Documentation**: Updates to `README.md`, `docs/`, or docstrings.
+- **🛠️ Maintenance**: Dependency updates, CI changes, or test refactoring.
+
+#### Writing Style
+- Use clear, action-oriented language (e.g., "Add support...", "Fix issue where...", "Refactor...").
+- Link to PRs and contributors using their GitHub handles.
+- Include a "Breaking Changes" section if applicable (use `[!WARNING]` alerts).
+
+### 4. Finalize
+
+Once the notes are drafted and refined, you can view the draft on GitHub or update it via CLI.
+
+```bash
+# View the draft notes
+gh release view v<version>
+
+# Edit the draft (opens your editor)
+gh release edit v<version> --notes "your new notes"
+```
+
+## Tips
+
+- **Consistency**: Refer to the `AGENTS.md` for project-specific terminology (e.g., "Upstream Layers").
+- **Screenshots**: If the release includes significantly visible changes (e.g., new logging or CLI output formats), consider embedding a screenshot or recording in the notes.
+- **Automated Summary**: You can ask the AI assistant to "Draft release notes based on the git log since <tag>" to get a structured summary before applying it to the release.

{ruff_sync-0.1.0.dev0 → ruff_sync-0.1.0.dev2}/.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
       - id: check-json
       - id: check-yaml
         args: ["--unsafe"]
+        exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: no-commit-to-branch
@@ -21,6 +22,7 @@ repos:
     hooks:
       - id: prettier
         types_or: [yaml, json]
+        exclude: .agents/skills/mkdocs-generation/templates/mkdocs.yml
   - repo: https://github.com/rhysd/actionlint
     rev: v1.7.11
     hooks:

{ruff_sync-0.1.0.dev0 → ruff_sync-0.1.0.dev2}/AGENTS.md

@@ -150,6 +150,7 @@ uv run coverage run -m pytest -vv
 - Use `pathlib` over `os.path` (enforced by `PTH` rules).
 - Prefer f-strings for logging (we ignore `G004`).
 - Do not create custom exception classes for simple errors (`TRY003` is ignored).
+- **Prefer `NamedTuple` for return types** over plain tuples to improve readability and type safety.
 
 ### TOML Handling
 

{ruff_sync-0.1.0.dev0 → ruff_sync-0.1.0.dev2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.0.dev0
+Version: 0.1.0.dev2
 Summary: Synchronize Ruff linter configuration across projects
 Project-URL: Homepage, https://github.com/Kilo59/ruff-sync
-Project-URL: Documentation, https://github.com/Kilo59/ruff-sync#readme
+Project-URL: Documentation, https://kilo59.github.io/ruff-sync/
 Project-URL: Repository, https://github.com/Kilo59/ruff-sync
 Project-URL: Issues, https://github.com/Kilo59/ruff-sync/issues
 Project-URL: Changelog, https://github.com/Kilo59/ruff-sync/releases
@@ -30,7 +30,7 @@ Requires-Dist: typing-extensions>=4.5.0
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Kilo59/ruff-sync/main/ruff_sync_banner.png" alt="ruff-sync banner" style="max-width: 600px; width: 100%; height: auto; margin-bottom: 1rem;">
+  <img src="https://raw.githubusercontent.com/Kilo59/ruff-sync/main/docs/assets/ruff_sync_banner.png" alt="ruff-sync banner" style="max-width: 600px; width: 100%; height: auto; margin-bottom: 1rem;">
   <br>
   <a href="https://pypi.org/project/ruff-sync/"><img src="https://img.shields.io/pypi/v/ruff-sync" alt="PyPI version"></a>
   <a href="https://codecov.io/gh/Kilo59/ruff-sync"><img src="https://codecov.io/gh/Kilo59/ruff-sync/graph/badge.svg?token=kMZw0XtoFW" alt="codecov"></a>
@@ -163,6 +163,7 @@ Run `ruff-sync --help` for full details on all available options.
 ## Key Features
 
 - 🏗️ **Format-preserving merges** — Uses [tomlkit](https://github.com/sdispater/tomlkit) under the hood, so your comments, whitespace, and TOML structure are preserved. No reformatting surprises.
+- 📂 **Upstream Layers** — Merge configurations from several sources sequentially (e.g., base company config + team-specific overrides).
 - 🌐 **GitHub & GitLab URL support** — Automatically converts GitHub/GitLab repository URLs, tree (directory) URLs, or blob (file) URLs to raw content URLs.
 - 🔍 **Smart configuration discovery** — Point at a directory and `ruff-sync` will automatically find your config. It checks `pyproject.toml`, `ruff.toml`, and `.ruff.toml` (in that order).
 - 📥 **Git clone support** — If the URL starts with `git@` or uses the `ssh://`, `git://`, or `git+ssh://` schemes, `ruff-sync` will perform an efficient shallow clone (using `--filter=blob:none` and `--no-checkout`) to safely extract the configuration with minimal network traffic.
@@ -200,8 +201,9 @@ Here are all the possible values that can be provided in `[tool.ruff-sync]` alon
 
 ```toml
 [tool.ruff-sync]
-# The source of truth URL for your Ruff configuration. (Required, unless passed via CLI)
-upstream = "https://github.com/my-org/standards"
+# The source of truth URL(s) for your Ruff configuration. (Required, unless passed via CLI)
+# Accepts a single string URL or a list of URLs.
+upstream = ["https://github.com/my-org/standards", "https://github.com/my-org/team-tweaks"]
 
 # A list of config keys to exclude from being synced. (Default: ["lint.per-file-ignores"])
 # Use simple names for top-level keys, and dotted paths for nested keys.
@@ -329,10 +331,13 @@ When you run `ruff-sync check`, it follows this process to determine if your pro
 ```mermaid
 flowchart TD
     Start([Start]) --> Local[Read Local Configuration]
-    Local --> Upstream[Download Upstream Configuration]
-    Upstream --> Extract[Extract tool.ruff section if needed]
+    Local --> Upstreams{For each Upstream}
+    Upstreams --> Download[Download/Clone Configuration]
+    Download --> Extract[Extract section if needed]
     Extract --> Exclude[Apply Exclusions]
-    Exclude --> Merge[Perform in-memory Merge]
+    Exclude --> Merge[Merge into in-memory Doc]
+    Merge --> Upstreams
+    Upstreams -- Done --> Comparison
 
     subgraph Comparison [Comparison Logic]
         direction TB