Repository navigation
feat!: use readable HTML anchors for Java declarations - #50
Merged
Merged
Conversation
r4sky0
enabled auto-merge (squash)
October 13, 2026 20:21
r4sky0
added a commit
that referenced
this pull request
Oct 13, 2026
Package pages showed the package comment as loose content, while types and members sit in object descriptions. Themes therefore styled a package's fields differently. In Lumina, for example, `Since` became a boxed page-level card on package pages but a two-column field on class pages. ## Changes - **Package declaration.** `java:autopackage` renders an object description with the declaration `package org.example`, as the standard doclet's package pages do. The package's anchor moves to that signature. The package documentation becomes its description, so fields render like those of types and members in every theme. - It adds no table of contents entry, so "On this page" still lists the type groups only. - `sphinx.ext.linkcode` sees an empty `source` and `line` for packages; resolvers written as documented already skip that. `docs/usage.rst` now says so. - A new integration test checks that the package page declares the package and holds its documentation. ## Checks run locally - `pre-commit` hooks: pass. - `pytest -q`: 138 passed. - Checked together with #50 in a combined tree: - `showcase/build.py`: warning counts equal the baseline in every theme. - `sphinx-build -W --keep-going -n docs`: passes. - Browser checks in all five themes: pass. - Lumina and Furo package pages look right by eye. Co-authored-by: Ralph Offinger <9093316+ralph089@users.noreply.github.com>
Contributor
|
Documentation preview for 298f5f8: https://r4sky0.github.io/sphinx-java-autodoc/pr-preview/pr-50/ |
Anchors were "java-" plus the hex-encoded canonical ID, so links such as They are now the canonical ID behind a "java:" prefix, with "#" written as "-" and "<init>" as "new", for example deterministic, reversible and collision-free: docutils never generates ":" in IDs, Java names never contain "-", and "new" cannot name a method. The Commons Lang showcase's searchindex.js shrinks from 2.3 MB to 1.6 MB. The browser checks now open a member anchor in every theme. BREAKING CHANGE: links and bookmarks to the old java-<hex> anchors no longer reach their declaration. Inventories are regenerated, so intersphinx links from other projects update after their next build.
r4sky0
force-pushed
the
feat/readable-anchors
branch
from
October 14, 2026 05:24
298f5f8 to
f541243
Compare
r4sky0
disabled auto-merge
October 14, 2026 05:24
r4sky0
pushed a commit
that referenced
this pull request
Oct 14, 2026
🤖 I have created a release *beep* *boop* --- ## [0.5.0](v0.4.0...v0.5.0) (2026-10-14) ### ⚠ BREAKING CHANGES * use readable HTML anchors for Java declarations ([#50](#50)) ### Features * declare packages on their pages, as Javadoc does ([#51](#51)) ([f24dfc1](f24dfc1)) * use readable HTML anchors for Java declarations ([#50](#50)) ([f75278e](f75278e)) --- 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Member links looked like
#java-6f72672e6170616368652e636f6d6d6f6e732e6c616e67332e537472696e675574696c73…: unreadable, impossible to write by hand, and a large part of every search index.Changes
Readable anchors. An anchor is now
java:plus the canonical ID, with#written as-and<init>asnew:#java:org.apache.commons.lang3.StringUtils-abbreviate(java.lang.String,int)#java:demo.Widget-new(java.lang.String)for constructors#java:demofor packagesThey stay deterministic, reversible and collision-free, as
docs/schema.mdpromises::in IDs, so the packagedemono longer risks clashing with the section IDdemoon its own page;-;newis a keyword and cannot name a method.The Commons Lang showcase's
searchindex.jsshrinks from 2.3 MB to 1.6 MB (gzip 216 KB to 183 KB).docs/schema.mddescribes the new rule.Tests:
tests/visual_check.pynow opens a member anchor in every theme. That fails on page errors from theme scripts that cannot handle:or(, and the check waits until the target is in view, because Lumina scrolls smoothly.Breaking change
Links and bookmarks to the old
java-<hex>anchors no longer reach their declaration; no aliases are kept. Inventories are regenerated, so intersphinx links from other projects update after their next build.Checks run locally
pre-commithooks: pass.pytest -q: 139 passed (rebased on feat: declare packages on their pages, as Javadoc does #51).showcase/build.py: warning counts equal the baseline in every theme.sphinx-build -W --keep-going -n docs: passes.tests/visual_check.py, after building the fixture in all five themes): pass. I also loaded a member anchor in Lumina at 390px by hand; the target lands below the fixed header, the same as a plain section anchor.