Skip to content

Fix docs build broken by sphinx-argparse commands domain#2551

Merged
jambayk merged 3 commits into
mainfrom
jambayk/doc-fix
Jul 1, 2026
Merged

Fix docs build broken by sphinx-argparse commands domain#2551
jambayk merged 3 commits into
mainfrom
jambayk/doc-fix

Conversation

@jambayk

@jambayk jambayk commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Describe your changes

sphinx-argparse 0.6.0 registers a commands domain (ArgParseDomain) that does not implement the standard Sphinx Domain.resolve_any_xref API. MyST falls back to calling the domain's resolve_xref for every markdown cross-reference, and that method logs Error, no command xref target from ... for each target it doesn't own, including links that already resolve via doc/std resolution. Under -W, this flood of warnings fails the docs build.

This adds a resolve_any_xref implementation to ArgParseDomain in docs/source/conf.py, supplying the API the extension omits so MyST resolves real command targets and skips the noisy fallback. This also removes the myst.domains legacy-domain warning, so the earlier suppress_warnings entry for it is dropped. No version pin is added to docs/requirements.txt.

The rendered HTML is byte-identical to before; only the spurious warnings are gone. The sphinx-build -W build passes.

Checklist before requesting a review

  • Add unit tests for this change.
  • Make sure all tests can pass.
  • Update documents if necessary.
  • Lint and apply fixes to your code by running lintrunner -a
  • Is this a user-facing change? If yes, give a description of this change to be included in the release notes.

(Optional) Issue link

Copilot AI review requested due to automatic review settings July 1, 2026 21:04

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Updates the Sphinx documentation configuration to silence a specific class of MyST-Parser warnings during docs builds, reducing noise from known/expected warnings in the Olive docs pipeline.

Changes:

  • Extends suppress_warnings in docs/source/conf.py to include myst.domains alongside the existing myst.xref_missing suppression.

…ommands domain

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jambayk jambayk changed the title Docs: Suppress myst.domains warnings Fix docs build broken by sphinx-argparse commands domain Jul 1, 2026
@jambayk jambayk force-pushed the jambayk/doc-fix branch from cd471d3 to d11bdd1 Compare July 1, 2026 21:34
@jambayk jambayk enabled auto-merge (squash) July 1, 2026 21:44
@jambayk jambayk merged commit 27132bd into main Jul 1, 2026
10 checks passed
@jambayk jambayk deleted the jambayk/doc-fix branch July 1, 2026 22:30
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.

3 participants