Skip to content

Fix unresolved xref placeholders in message_mapper.py DocFx output#242

Merged
JimDaly merged 3 commits intomainfrom
copilot/fix-broken-cross-reference-links
Apr 29, 2026
Merged

Fix unresolved xref placeholders in message_mapper.py DocFx output#242
JimDaly merged 3 commits intomainfrom
copilot/fix-broken-cross-reference-links

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Apr 24, 2026

Short RST :class: roles (e.g. :class:InputMessages``) cause DocFx to emit unresolvable <xref:InputMessages> placeholders in generated API docs instead of rendered links.

Changes

  • agentframework/message_mapper.py — Replace all four :class:`` occurrences (module docstring, map_input_messages, map_output_messages, _map_role`) with plain double-backtick code formatting
  • openai/message_mapper.py — Same fix for map_input_messages and map_output_messages return-value docs

Before / After

# Before — triggers unresolvable <xref:InputMessages> in DocFx
"""
This mapper converts them to :class:`InputMessages` / :class:`OutputMessages`.
...
Returns:
    Serialized :class:`InputMessages` JSON string, or ``None`` if ...
"""

# After — plain code formatting, consistent with langchain/message_mapper.py
"""
This mapper converts them to ``InputMessages`` / ``OutputMessages``.
...
Returns:
    Serialized ``InputMessages`` JSON string, or ``None`` if ...
"""

Copilot AI changed the title [WIP] Fix broken cross-reference links in message_mapper.py docstrings Fix unresolved xref placeholders in message_mapper.py DocFx output Apr 24, 2026
Copilot AI requested a review from JimDaly April 24, 2026 20:50
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 24, 2026

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

@JimDaly JimDaly marked this pull request as ready for review April 24, 2026 21:18
@JimDaly JimDaly requested a review from a team as a code owner April 24, 2026 21:18
Copilot AI review requested due to automatic review settings April 24, 2026 21:18
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Fixes DocFx API doc generation by avoiding short RST :class: roles that DocFx renders as unresolved <xref:...> placeholders in generated documentation.

Changes:

  • Replace :class: references with double-backtick inline code in Agent Framework message_mapper.py docstrings (module + function docs + helper doc).
  • Apply the same docstring formatting fix to OpenAI message_mapper.py return-value docs.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File Description
libraries/microsoft-agents-a365-observability-extensions-agentframework/microsoft_agents_a365/observability/extensions/agentframework/message_mapper.py Switches :class: references to inline code to prevent unresolved xref placeholders in DocFx output.
libraries/microsoft-agents-a365-observability-extensions-openai/microsoft_agents_a365/observability/extensions/openai/message_mapper.py Updates return docstrings to use inline code formatting for message wrapper types, preventing DocFx xref placeholders.

@JimDaly JimDaly enabled auto-merge (squash) April 29, 2026 17:19
@JimDaly JimDaly merged commit 7913115 into main Apr 29, 2026
9 checks passed
@JimDaly JimDaly deleted the copilot/fix-broken-cross-reference-links branch April 29, 2026 19:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix broken cross-reference links in message_mapper.py docstrings

5 participants