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
Problem
Generated doc page: CustomLangChainTracer Class
The DocFx-generated API page for
CustomLangChainTracerinlibraries/microsoft-agents-a365-observability-extensions-langchain/microsoft_agents_a365/observability/extensions/langchain/tracer.pyproduces 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: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:
Category 2: Raw GitHub source URLs in
on_chat_model_startdocstring (code fix)The
on_chat_model_startmethod docstring contains three rawhttps://github.com/langchain-ai/langchain/blob/...URLs. These appear asliteral 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: