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

[daviburg]

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 /// <summary> 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/<moniker>/).
  • 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).
• Tracked in the EPIX dashboard as a sub-issue of Azure/azure-functions-bucees-planning#902.

[daviburg]

Reference-docs onboarding request filed: ADO User Story 593111 (msft-skilling/Content) — https://dev.azure.com/msft-skilling/Content/_workitems/edit/593111

Submitted via the Learn "Onboard reference content" template with:

• Language / source: .NET from NuGet — Azure.Connectors.Sdk, 0.12.0-preview.1 (prerelease)
• Moniker: azure.connectors.sdk (Is prerelease); docset: azure.connectors.sdk
• ms.service: connector-namespace (slug approval pending — per content authority Esther Fan)
• Type: client; released outside the Azure SDK Engineering System (own repo/pipelines)
• Related metadata correction: Correct Azure.Connectors.Sdk release metadata azure-sdk#10098 (draft — blocked on the connector-namespace slug)

Next: Pubdesk ~3-day SLA → a review PR for the generated .NET reference. The ms.service value is reconciled when the connector-namespace slug is approved; the pending slug is not a blocker for filing (DevRel sets up the docset from the package + suggested moniker).