Skip to content

fix: resolve summary links through intersphinx, nested external types, signature-only types and spaced member spellings - #74

Merged
r4sky0 merged 5 commits into
mainfrom
fix/reference-resolution
Nov 11, 2026
Merged

r4sky0 merged 5 commits into
mainfrom
fix/reference-resolution

Conversation

@r4sky0

@r4sky0 r4sky0 commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Summary

Four cases where a reference that could resolve did not.

 summary or "Overrides" link into another Sphinx project
-  the text fallback ran at intersphinx's priority, so extension order decided
+  the fallback runs at priority 900, after intersphinx (500)

 :java:type:`vendor.api.util.Thing` with {"vendor.api": ...} and no compiler metadata
-  .../vendor/api/util.Thing.html
+  .../vendor/api/util/Thing.html      the type starts at the first capitalized name

 :java:type:`java.util.List`, where List appears only in a signature
-  ref.type warning: locations came from {@link} only
+  resolved: locations also come from signature types and @throws

 :members: find(String, int)    and the same line in java:autosummary
-  "not found": only java:automethod removed spaces and mapped ... to []
+  one helper normalises the spelling in every directive and in roles

docs/usage.rst describes the fallback URL rule, the spelling rule and where external locations come from.

Evidence

  • Before: test_intersphinx_resolves_summary_links_before_text_fallback fails (the link stays plain text). Two new cases of test_external_urls fail with util.Thing.Inner.html. test_manual_role_uses_signature_metadata fails with ref.type. test_member_spellings_are_normalised_in_every_directive fails with "not found" warnings.
    After: all pass.
  • test_external_locations_come_from_links_throws_and_signatures was written after the fix and never seen failing.
  • On this branch: pytest -q 145 passed, pre-commit run --all-files passes, sphinx-build -W --keep-going -n docs passes.
  • Not run on this branch alone: the showcase build and the browser checks.

Merge Danger

Door: two-way

Blast Radius: links

Links that were plain text or dead start to resolve. The URL fallback relies on Java naming: with no capitalized name in the reference, the type starts right after the mapped prefix, as before. An unresolved link never replaces a known location for the same target.

quiet_reference turns unresolved summary and Overrides links into text.
At the default priority it ran before intersphinx whenever this
extension was listed first, as docs/usage.rst shows, so such links to
another Sphinx project stayed text. It now runs at priority 900.
Without compiler metadata, the URL assumed that the mapped prefix was
the exact package, so vendor.api.util.Thing under vendor.api became
vendor/api/util.Thing.html. The type now starts at the first
capitalized name, or after the prefix when no name is capitalized.
Only java:automethod and roles removed spaces and mapped ... to [],
so :members: find(java.lang.String, int) and java:autosummary entries
with spaces or varargs warned "not found". One helper now normalises
java:automethod and java:autofield arguments, java:autosummary lines,
:members: and :exclude-members: entries, and role targets.
External Javadoc metadata came only from comment links, so a role to
a JDK type that appeared only in signatures or @throws, such as
:java:type:`java.util.List`, found no module and stayed unresolved
under a {module} mapping. use_model now also reads signature types and
throws parts, and an entry with a location is never replaced by an
unresolved link.
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

@r4sky0
r4sky0 enabled auto-merge (squash) November 11, 2026 05:36
@r4sky0
r4sky0 merged commit b75a4ce into main Nov 11, 2026
19 checks passed
@r4sky0
r4sky0 deleted the fix/reference-resolution branch November 11, 2026 06:58
r4sky0 added a commit that referenced this pull request Nov 14, 2026
🤖 I have created a release *beep* *boop*
---


##
[0.7.0](v0.6.0...v0.7.0)
(2026-11-11)


### Features

* render more Javadoc HTML and inline tags natively, and highlight
<pre> leniently
([#72](#72))
([6b851cb](6b851cb))
* report implicit inheritance failures as java.inherit and warn about
unresolved [@throws](https://github.com/throws)
([#73](#73))
([a940118](a940118))


### Bug Fixes

* publish files with the umask's permissions, ignore JVM option notices
and accept an integer java_release
([#70](#70))
([99b9a76](99b9a76))
* resolve summary links through intersphinx, nested external types,
signature-only types and spaced member spellings
([#74](#74))
([b75a4ce](b75a4ce))
* show modifiers, field order and <br> summaries as the standard
doclet does
([#71](#71))
([cd7cd85](cd7cd85))
* survive links to type parameters and modules, and table rows without
cells ([#69](#69))
([b4127fc](b4127fc))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: r4sky0 <9093316+r4sky0@users.noreply.github.com>
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.

1 participant