Repository navigation
feat: declare packages on their pages, as Javadoc does - #51
Merged
Merged
Conversation
Package pages showed the package comment as loose content, so themes styled its fields (Since, See also) unlike the same fields on types and members. java:autopackage now renders an object description with the declaration "package org.example", the package's anchor and its documentation, matching the standard doclet's package pages. It adds no table of contents entry. sphinx.ext.linkcode sees an empty source and line for packages, which documented resolvers already skip.
r4sky0
enabled auto-merge (squash)
October 13, 2026 20:22
Contributor
|
Documentation preview for 1a1fb58: https://r4sky0.github.io/sphinx-java-autodoc/pr-preview/pr-51/ |
r4sky0
added a commit
that referenced
this pull request
Oct 14, 2026
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>` as `new`: - `#java:org.apache.commons.lang3.StringUtils-abbreviate(java.lang.String,int)` - `#java:demo.Widget-new(java.lang.String)` for constructors - `#java:demo` for packages They stay deterministic, reversible and collision-free, as `docs/schema.md` promises: - docutils never generates `:` in IDs, so the package `demo` no longer risks clashing with the section ID `demo` on its own page; - Java names never contain `-`; - `new` is a keyword and cannot name a method. The Commons Lang showcase's `searchindex.js` shrinks from 2.3 MB to 1.6 MB (gzip 216 KB to 183 KB). - `docs/schema.md` describes the new rule. - Tests: - A new integration test pins the format for members, constructors and packages. - It checks that the package anchor and the package page's section ID coexist, and that no generated page has duplicate IDs. - `tests/visual_check.py` now 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-commit` hooks: pass. - `pytest -q`: 139 passed (rebased on #51). - `showcase/build.py`: warning counts equal the baseline in every theme. - `sphinx-build -W --keep-going -n docs`: passes. - Browser checks (`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. Co-authored-by: Ralph Offinger <9093316+ralph089@users.noreply.github.com>
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.
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,
Sincebecame a boxed page-level card on package pages but a two-column field on class pages.Changes
java:autopackagerenders an object description with the declarationpackage 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.sphinx.ext.linkcodesees an emptysourceandlinefor packages; resolvers written as documented already skip that.docs/usage.rstnow says so.Checks run locally
pre-commithooks: pass.pytest -q: 138 passed.showcase/build.py: warning counts equal the baseline in every theme.sphinx-build -W --keep-going -n docs: passes.