Skip to content

Fix broken DocFx cross-reference links in span_processor, observability_hosting_manager, output_logging_middleware, and utils docstrings #243

@JimDaly

Description

@JimDaly

Problem

Several API documentation pages show unresolved xref placeholders instead of rendered links. This is the same pattern identified in #241, affecting four additional files.

Root cause

Docstrings use short RST cross-references such as :class:EnrichedReadableSpan``. The DocFx toolchain converts these to <xref:EnrichedReadableSpan> and attempts to qualify the name using the current module. This fails whenever the referenced class is imported from another module rather than defined in the same file — DocFx resolves xrefs to definition sites, not import sites. The same problem occurs with `:meth:` references that omit the module path.

Fix

Replace each short reference with the fully-qualified dotted name of the definition site. No logic changes are needed — this is a docstring-only fix.

Instances to fix

File Line Current Replace with
libraries/microsoft-agents-a365-observability-extensions-agentframework/microsoft_agents_a365/observability/extensions/agentframework/span_processor.py 10 :class:EnrichedReadableSpan`` :class:microsoft_agents_a365.observability.core.exporters.enriched_span.EnrichedReadableSpan``
libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/observability_hosting_manager.py 44 :meth:configure`` :meth:microsoft_agents_a365.observability.hosting.middleware.observability_hosting_manager.ObservabilityHostingManager.configure``
libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/observability_hosting_manager.py 62 :class:ObservabilityHostingManager`` :class:microsoft_agents_a365.observability.hosting.middleware.observability_hosting_manager.ObservabilityHostingManager``
libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/output_logging_middleware.py 88 :class:OutputScope`` :class:microsoft_agents_a365.observability.core.spans_scopes.output_scope.OutputScope``
libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/utils.py 69 :meth:OpenTelemetryScope.inject_context_to_headers`` :meth:microsoft_agents_a365.observability.core.opentelemetry_scope.OpenTelemetryScope.inject_context_to_headers``

Related

Closes part of the same pattern reported in #241.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions