feat(docs): add api-docs template for dotnet-sdk (xmldocmd)

[WomB0ComB0]

Summary

Adds the second per-language workflow template, mirroring the TypeScript pipeline for .NET.

• New file: automation/source-repo-templates/api-docs.dotnet.yml
• README table: dotnet-sdk row updated from DocFX / _TODO_ placeholder to xmldocmd / api-docs.dotnet.yml

Pipeline

1. actions/setup-dotnet honoring global.json (.NET 9 today).
2. dotnet build -c Release -p:GenerateDocumentationFile=true to emit the per-project XML doc files alongside DLLs.
3. dotnet tool install -g xmldocmd then iterate over six packable projects (ResQ.Clients, ResQ.Core, ResQ.Protocols, ResQ.Blockchain, ResQ.Storage, ResQ.Simulation), invoking xmldocmd <dll> <out>/<proj> --visibility public --clean.
4. Same Mintlify-safety post-processing as the TypeScript template:
   • ./ prefix on bare-filename .md links
   • MDX curly-brace escape outside code regions (awk tracks both fences and inline backtick spans)
5. peter-evans/create-pull-request opens a PR back to resq-software/docs against main, branch auto/dotnet-api-<ref>, authored as resq-sw.

Why xmldocmd over DocFX

xmldocmd is a purpose-built CLI tool that takes a DLL + XML pair and produces Markdown. DocFX is more powerful but its Markdown output requires a custom template (its native output is HTML). For the simpler shape we want, xmldocmd is one-step.

Test plan

• Merge.
• Open a follow-up PR in resq-software/dotnet-sdk copying this file to .github/workflows/api-docs.yml.
• Trigger via workflow_dispatch and inspect the resulting docs PR for unexpected post-processing failures.
• If new generator-specific quirks appear (breadcrumb noise, anchor format, etc.), iterate the template here first then sync to dotnet-sdk.

Out of scope

• Wiring nav for sdks/dotnet/api/ in docs.json (deferred along with the TypeScript nav).
• Templates for Python (mkdocstrings), Rust (rustdoc), C++ (Doxygen), and viz.

Summary by CodeRabbit

• Documentation

  • Updated API documentation tooling configuration for the C# SDK.

• Automation

  • Added automated workflow to generate .NET API documentation, post-process content, and sync updates to the documentation repository via automated pull requests.

[coderabbitai]

Warning

Rate limit exceeded

@WomB0ComB0 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 30 minutes and 37 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 208145a8-f38a-424c-969c-9e7c01f6d422

📥 Commits

Reviewing files that changed from the base of the PR and between 7f7875c and 65a4f1c.

📒 Files selected for processing (2)

• automation/source-repo-templates/README.md
• automation/source-repo-templates/api-docs.dotnet.yml

📝 Walkthrough

Walkthrough

This pull request introduces a GitHub Actions workflow that automates .NET API documentation generation. The workflow checks out source, builds projects to generate XML docs, converts them to Markdown via xmldocmd, post-processes the Markdown for link safety and MDX compatibility, syncs to a docs repository, and creates a PR. The README is updated to reference the new workflow template.

Changes

.NET API Documentation Automation

Layer / File(s)	Summary
Workflow Declaration & Triggers automation/source-repo-templates/api-docs.dotnet.yml	Workflow api-docs triggers on v* tags and manual dispatch with optional ref input; permissions and concurrency configured to force-cancel in-flight runs.
Job Setup & Environment automation/source-repo-templates/api-docs.dotnet.yml	Job defines runner settings, timeout, and environment variables for solution path, output directories, target docs path, and list of public projects to document.
Source Checkout & Build automation/source-repo-templates/api-docs.dotnet.yml	Checks out source at requested ref, installs .NET via global.json, restores solution, and builds Release configuration to generate XML documentation.
API Documentation Generation automation/source-repo-templates/api-docs.dotnet.yml	Installs xmldocmd tool and generates per-project Markdown trees from built DLLs under bin/Release/net9.0/.
Markdown Post-Processing automation/source-repo-templates/api-docs.dotnet.yml	Writes top-level README.md, prefixes bare .md intra-page links with ./ via find + sed, and escapes { } to HTML entities outside code blocks via awk for MDX safety.
Index Creation & Repository Sync automation/source-repo-templates/api-docs.dotnet.yml	Creates _pages.json index, checks out resq-software/docs repo, deletes old content, and syncs generated Markdown to sdks/dotnet/api.
Pull Request Creation automation/source-repo-templates/api-docs.dotnet.yml	Opens or updates PR in docs repo with scoped paths, deterministic auto-generated branch name, and configured cleanup.
Template Registry Update automation/source-repo-templates/README.md	Updates tooling table to reference xmldocmd with template api-docs.dotnet.yml for .NET SDK documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A rabbit hops through workflows new,
xmldocmd turns DLLs true to view,
Markdown grows with each tag's release,
Links are fixed, the {} find peace,
To the docs repo, a PR takes flight!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a new API documentation template for .NET SDK using xmldocmd, which aligns with the primary objective of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-docs-dotnet-template

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@automation/source-repo-templates/api-docs.dotnet.yml`:
- Around line 103-113: The current loop over PUBLIC_PROJECTS skips missing
assembly files with a warning which can lead to a destructive sync publishing
incomplete docs; modify the check around
dll="${proj}/bin/Release/net9.0/${proj}.dll" so that if [ ! -f "$dll" ] then
emit an error and exit with a non-zero status (fail the job) instead of
continuing, ensuring the workflow halts before the later destructive sync (see
the loop and the xmldocmd invocation that writes to OUTPUT_DIR/$proj); apply the
same failing behavior to the other similar check at lines 206-212.
- Around line 42-43: The workflow mixes github.ref/github.ref_name and
inputs.ref causing inconsistent branch names and PR collisions; resolve the
requested ref once (e.g., compute a single resolved_ref from inputs.ref ||
github.ref_name in a step or job-level env) and use that resolved_ref
everywhere—replace group: api-docs-${{ github.ref }}, the checkout step(s) that
currently use inputs.ref, and the PR/branch name construction (the logic around
creating the docs PR branch) to reference the single resolved_ref variable
(e.g., env.RESOLVED_REF or a step output like steps.resolve_ref.outputs.ref) so
all metadata and branch names are consistent for workflow_dispatch and other
triggers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9afb5d79-b666-4e38-a5b7-094962818146

📥 Commits

Reviewing files that changed from the base of the PR and between 0c8af02 and 7f7875c.

📒 Files selected for processing (2)

• automation/source-repo-templates/README.md
• automation/source-repo-templates/api-docs.dotnet.yml

[gemini-code-assist]

Code Review

This pull request introduces a new GitHub Actions workflow template, api-docs.dotnet.yml, designed to automate the generation of .NET API documentation using xmldocmd. The workflow handles building the solution, generating Markdown documentation for public projects, and performing post-processing for MDX compatibility before opening a pull request in the central documentation repository. Feedback focuses on improving the template's maintainability and robustness by dynamically discovering packable projects and locating build artifacts instead of relying on hardcoded paths and project lists.