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

ruff_sync-0.1.0.dev1/.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.dev1/.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.dev1/.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.dev1/.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.dev1/.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.dev1/.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.dev0 → ruff_sync-0.1.0.dev1}/.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.dev1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.0.dev0
+Version: 0.1.0.dev1
 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>

{ruff_sync-0.1.0.dev0 → ruff_sync-0.1.0.dev1}/README.md

@@ -1,5 +1,5 @@
 <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>

ruff_sync-0.1.0.dev1/docs/ci-integration.md

@@ -0,0 +1,106 @@
+# CI Integration
+
+`ruff-sync` is designed to be run in CI pipelines to ensure that all repositories in an organization stay in sync with the central standards.
+
+## Usage in CI
+
+The best way to use `ruff-sync` in CI is with the `check` command. If the configuration has drifted, `ruff-sync check` will exit with a non-zero code, failing the build.
+
+### GitHub Actions
+
+We recommend using `uv` to run `ruff-sync` in GitHub Actions.
+
+#### Basic Check
+
+```yaml
+name: "Standards Check"
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  ruff-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uvx ruff-sync check --semantic
+```
+
+#### Automated Sync PRs
+
+Instead of just checking, you can have a bot automatically open a PR when the upstream configuration changes.
+
+```yaml
+name: "Upstream Sync"
+
+on:
+  schedule:
+    - cron: '0 0 * * 1' # Every Monday at midnight
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Pull upstream
+        run: uvx ruff-sync pull
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore: sync ruff configuration from upstream"
+          title: "chore: sync ruff configuration"
+          body: "This PR synchronizes the Ruff configuration with the upstream source."
+          branch: "ruff-sync-update"
+```
+
+### GitLab CI
+
+```yaml
+ruff-sync-check:
+  image: python:3.12
+  script:
+    - pip install ruff-sync
+    - ruff-sync check --semantic
+  only:
+    - merge_requests
+    - main
+```
+
+---
+
+## 🛠️ Pre-commit Integration
+
+You can use `ruff-sync` with `pre-commit` to ensure your configuration is always in sync before pushing.
+
+Add this to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-sync-check
+        name: ruff-sync-check
+        entry: uvx ruff-sync check --semantic
+        language: system
+        files: ^pyproject\.toml$
+        pass_filenames: false
+```
+
+!!! note
+    Running `ruff-sync check` in pre-commit is fast because it only performs a network request if the local `pyproject.toml` is older than the upstream or if no cache exists.
+
+---
+
+## 💡 Best Practices
+
+### Use `--semantic`
+
+In CI, you usually only care about the functional configuration. Using `--semantic` ensures that minor formatting changes don't break your builds, while still guaranteeing that the actual rules are identical.
+
+### Use a Dedicated Workflow
+
+Running `ruff-sync` as a separate job in your linting workflow makes it easy to identify when a failure is due to configuration drift rather than a code quality issue.