Skip to content

Fix broken cross-reference links and raw GitHub URLs in CustomLangChainTracer docstrings #245

@JimDaly

Description

@JimDaly

Problem

Generated doc page: CustomLangChainTracer Class

The DocFx-generated API page for CustomLangChainTracer in
libraries/microsoft-agents-a365-observability-extensions-langchain/microsoft_agents_a365/observability/extensions/langchain/tracer.py
produces dozens of unresolved cross-reference warnings and contains raw GitHub source URLs that appear as literal links in the published docs.

The warnings and the GitHub URLs fall into two categories with different fixes.


Category 1: Google-style type annotation in __init__ docstring (code fix)

The __init__ docstring uses Google-style parenthesised type annotations:

Args:
    tracer (trace_api.Tracer): The OpenTelemetry tracer for creating spans.
    separate_trace_from_runtime_context (bool): ...
    *args (Any): ...
    **kwargs (Any): ...

DocFx extracts the parenthesised strings as type cross-references and generates
<xref:trace_api.Tracer>, <xref:Any>, etc. — none of which it can resolve.

Fix: Remove the parenthesised types from the Google-style format. The types are
already present on the function signature and do not need to be repeated in the
docstring body. The corrected docstring should be:

def __init__(
    self,
    tracer: trace_api.Tracer,
    separate_trace_from_runtime_context: bool,
    *args: Any,
    **kwargs: Any,
) -> None:
    """Initialize the CustomLangChainTracer.

    Args:
        tracer: The OpenTelemetry tracer for creating spans.
        separate_trace_from_runtime_context: When True, always start a new
            trace for each span without a parent, isolating it from any
            existing trace in the runtime context.
        *args: Positional arguments forwarded to BaseTracer.
        **kwargs: Keyword arguments forwarded to BaseTracer.
    """

Category 2: Raw GitHub source URLs in on_chat_model_start docstring (code fix)

The on_chat_model_start method docstring contains three raw
https://github.com/langchain-ai/langchain/blob/... URLs. These appear as
literal hyperlinks on the published docs page pointing at LangChain's source
code rather than its API reference, which is confusing for readers.

Fix: Remove the raw GitHub URLs. Replace the docstring with a brief plain-text
explanation of why this override exists, without linking to implementation
internals:

def on_chat_model_start(self, *args: Any, **kwargs: Any) -> Run:
    """Handle chat model start events.

    Delegates to ``LangChainTracer.on_chat_model_start`` to obtain correct
    chat-formatted spans. The ``BaseTracer`` implementation requires setting
    an internal ``_schema_format`` flag; delegating to ``LangChainTracer``
    avoids depending on that private attribute.
    """
    return LangChainTracer.on_chat_model_start(self, *args, **kwargs)  # type: ignore

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