Azure / Azure/Connectors-NET-SDK

Docs: publish Connectors SDK documentation (conceptual + .NET API reference; Python/Node to follow)

Open
#197 3 comments 0 reactions 1 assignee Claimed by @daviburg View on GitHub
documentation upstream
Dominant language
C#
Stars
3
Forks
5
Avg merge
1d 15h
Merged PRs (30d)
7

Description

## Summary

Track the work to publish public documentation for the **Azure Logic Apps Connectors SDK** (`Azure.Connectors.Sdk`). Documentation has two parts:

- **A. Conceptual / introductory docs** - hand-authored content under the **Connector Namespace** umbrella.
- **B. API reference docs** - tool-generated from the SDK's generated client classes. **Start with .NET; Python and Node.js to follow.**

## Fundamental rule

The API **reference must be driven from the generated client classes** (the compiled assembly + its XML doc comments), **not** from the source swagger. The generator corrects, trims, and renames the connector contracts on the fly for a premium experience, so the swagger is not a faithful description of the public surface.

## A. Conceptual docs

- **Home:** `articles/logic-apps/connector-namespace/` in `MicrosoftDocs/azure-docs-pr` (the SDK sits under the Connector Namespace ARM RP umbrella).
- Authored as Markdown following the Azure Logic Apps content style rules (service name "Azure Logic Apps", instance "logic app(s)", 2nd person, no informal acronyms, Oxford comma, descriptive link text, etc.).
- The SDK repo already has starter material in `docs/` (`concepts.md`, `connection-setup.md`).
- **Taxonomy note (Esther Fan):** Connector Namespace currently lives under `azure-logic-apps`; it will need its own service slug, folder, and ToC. Post-Build remediation.

## B. .NET API reference - onboard via the Microsoft Learn .NET reference pipeline

Per the Microsoft Learn Platform Manual ".NET reference requirements" and the Azure SDK "Publish SDK reference docs" process (the package is **released outside the Azure SDK engineering system, by design**):

- .NET managed reference is generated by the **Developer Relations / Learn API Docs team** from **NuGet packages (preferred)** + XML comment files, via the toolchain: **NuGet -> CI (mdoc reflection) -> ECMAXML -> OPS build -> YAML -> .NET API Browser** on `learn.microsoft.com/dotnet/api`.
- `Azure.Connectors.Sdk` is on NuGet and builds an XML documentation file (`GenerateDocumentationFile=true`); the generated `*Extensions.cs` carry `/// ` comments. -> satisfies the fundamental rule.
- **Onboarding steps:**
- [ ] Submit an **"Onboard reference content"** work item (DevRel sets up the docset; ~3-day SLA -> PR to review).
- [ ] Add CSV metadata for the package in `Azure/azure-sdk` (`Package`, `VersionGA`/`VersionPreview`, `DisplayName`, `ServiceName`, `MSDocService`, `Type=client`).
- [ ] Provide the package-level overview README in `MicrosoftDocs/azure-docs-sdk-dotnet` (`api/overview/azure//`).
- [ ] Choose a **moniker** for the package (preview boilerplate while in preview).
- [ ] Verify the package's dependency closure is consumable by the pipeline (CI requires package dependencies to be resolvable; manual DLL copying is unsupported).

### Scope decision: not `azure-logic-apps-ref-pr`

`MicrosoftDocs/azure-logic-apps-ref-pr` hosts the **built-in connectors conceptual reference** (DocFX `Conceptual` docset). The Platform Manual requires a **.NET reference repo to contain only .NET reference content** (no conceptual mixing), so the SDK's .NET API reference does **not** belong there. It is onboarded to the managed .NET API Browser ecosystem (`azure-docs-sdk-dotnet` + `Azure/azure-sdk`) instead.

## Coordination / dependencies

- **Wagner Silveira (PM):** creating the Learn area for the Connector Namespace RP and specifying the reference doc format. Shared a Copilot agent/skills sample (`wsilveiranz/logicapps-sdk-docs-files`) - well-suited to the small hand-authored Workflow SDK and to conceptual pages, but a per-class AI pass does not fit the ~1,460 auto-generated connector clients; the managed .NET reference pipeline does.
- **Esther Fan:** content authority; owns the built-in connectors reference; provided the onboarding pointer and style rules.
- Coordination chat: "Connectors SDK reference docs" (Teams).

## Follow-ups

- [ ] Python reference: `pypi` package -> `MicrosoftDocs/azure-docs-sdk-python` (Python requirements).
- [ ] Node.js reference: `npm` package -> `MicrosoftDocs/azure-docs-sdk-node` (JavaScript requirements).
- [x] Tracked in the EPIX dashboard as a sub-issue of Azure/azure-functions-bucees-planning#902.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.