Skip to content

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

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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