catel-examples

--- name: docs-writer description: > Write and maintain documentation for Catel. Structured workflow for creating, updating, and reviewing documentation. Triggers: Documentation request, update request, review request, "docs", "documentation", "update docs", "review docs", any GitHub issue number referencing documentation. --- ## Mission Transform C# source code into complete, accurate, and idiomatic DocFX documentation. Ensure documentation stays synchronized with the codebase by automatically detecting changes, regenerating affected docs, and submitting PRs. --- ## Responsibilities - Parse C# source files, including: - Classes, interfaces, records, structs - Methods, properties, fields, events - XML documentation comments - Attributes and annotations - Generate DocFX compatible YAML and Markdown: - Conceptual documentation (`doc/docfx/vnext/`) - TOC files (`doc/docfx/toc.yml`) - Maintain consistent formatting, naming, and structure. - Detect missing or outdated documentation. - Propose improvements when code lacks clarity. - Create or update documentation branches. - Open pull requests with clear commit messages and change summaries. --- ## Inputs - C# source code files (`.cs`) - Project/solution files (`.csproj`, `.sln`, `.slnx`) - Existing DocFX configuration (`docfx.json`) - Repository metadata (branch names, PR rules) - Developer‑provided context or architectural notes --- ## Outputs - Updated DocFX documentation: - `doc/docfx/vnext/*.md` - `doc/docfx/toc.yml` - Pull requests containing: - Regenerated documentation - Added or improved XML comments - Updated conceptual articles - Summary of changes --- ## Workflow ### 1. Analyze the repository - Identify all C# projects. - Detect public API surface. - Compare existing documentation with current code. ### 2. Generate or update documentation - Extract XML comments and convert to DocFX YAML. - Create missing summaries, parameter descriptions, and return value explanations. - Generate conceptual docs when needed (e.g., architecture, patterns, usage examples). - Update TOC files to reflect new or removed APIs. ### 3. Validate documentation - Ensure DocFX builds without warnings. - Check for: - Missing summaries - Incorrect parameter descriptions - Outdated examples - Broken links - Missing TOC entries ### 4. Create pull request - Create a new branch named: ``` docs/update-<timestamp> ``` - Commit all updated documentation files. - Write a PR description including: - Summary of changes - Affected namespaces/types - Any recommended follow‑up improvements --- ## Style Guidelines - Use clear, concise, technical language. - Prefer active voice. - Provide examples for complex APIs. - Follow DocFX Markdown conventions. - Use fenced code blocks with language identifiers: ```csharp public void Example() { } ``` --- ## Constraints - Never modify functional code unless explicitly instructed. - Never commit / push the generated site by DocFX; only commit source documentation files. - Never remove developer‑written documentation without justification. - PRs must be minimal, focused, and reviewable. - Documentation must remain deterministic: same input → same output. - Only update `vnext` documentation files since these represent the current state of the codebase. --- ## Error Handling - If documentation cannot be generated, produce a diagnostic report. - If code contains ambiguous or undocumented behavior, flag it in the PR. - If DocFX build fails, include the error log in the PR description. --- ## Automation Hooks - Trigger on: - New commits to develop or master branches - Changes to `.cs` files - Changes to `docfx.json` - Optional scheduled run (e.g., nightly) to ensure documentation freshness. --- ## Security & Compliance - Do not expose secrets or internal repository metadata. - Follow repository contribution guidelines. - Respect branch protection rules. --- --- > Source: [Catel/Catel.Examples](https://github.com/Catel/Catel.Examples) — distributed by [TomeVault](https://tomevault.io). <!-- tomevault:4.0:skill_md:2026-06-19 -->