sphinx-java-autodoc 0.4.0__tar.gz → 0.5.0__tar.gz

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sphinx-java-autodoc
-Version: 0.4.0
+Version: 0.5.0
 Summary: Compiler-backed Java API documentation in native Sphinx nodes
 Project-URL: Documentation, https://r4sky0.github.io/sphinx-java-autodoc/
 Project-URL: Repository, https://github.com/r4sky0/sphinx-java-autodoc

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/docs/schema.md

@@ -71,8 +71,11 @@ Identity examples: `example.Outer.Inner`, `example.Outer#FIELD`,
 Parameters in canonical IDs are fully qualified erased types; varargs use `[]`.
 External Javadoc fragments instead preserve declared type variables and use `...`
 for varargs, as verified against the standard doclet. Return types and
-parameter names do not affect IDs. HTML anchors are `java-` plus UTF-8 bytes of the
-ID encoded in hexadecimal: deterministic, reversible and collision-free.
+parameter names do not affect IDs. HTML anchors are `java:` plus the ID, with `#`
+replaced by `-` and `<init>` by `new`, as in `java:example.Outer-find(java.lang.String,int[])`
+and `java:example.Outer-new()`. They are deterministic, reversible and collision-free:
+docutils never generates `:` in IDs, Java names never contain `-`, and the keyword
+`new` cannot name a method.
 
 Declarations and diagnostics are sorted; no build timestamp or source path is
 stored. Renderers derive a declaration's file from its package and top-level type

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/docs/usage.rst

@@ -154,7 +154,8 @@ source root, such as ``com/example/Widget.java``) and ``line``:
            f"{info['source']}#L{info['line']}"
        )
 
-``line`` is empty for compiler-generated members, such as an enum's ``values()``.
+``line`` is empty for packages and for compiler-generated members, such as an enum's
+``values()``.
 With several source roots, choose the root in ``linkcode_resolve``, for example by
 checking which root contains ``source``.
 

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sphinx-java-autodoc"
-version = "0.4.0"
+version = "0.5.0"
 description = "Compiler-backed Java API documentation in native Sphinx nodes"
 readme = "README.md"
 requires-python = ">=3.12"

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/src/sphinx_java_autodoc/domain.py

@@ -29,7 +29,9 @@ LOGGER = logging.getLogger(__name__)
 
 
 def anchor(symbol: str) -> str:
-    return "java-" + symbol.encode("utf-8").hex()
+    # Docutils IDs never contain ":", Java names never contain "-", and the keyword
+    # "new" cannot name a method, so these readable anchors cannot collide.
+    return "java:" + symbol.replace("#<init>(", "#new(").replace("#", "-")
 
 
 def role_for(element):
@@ -304,13 +306,28 @@ class AutoPackage(JavaDirective):
             self.missing("package", package, "package")
             return []
         domain = self.env.get_domain("java")
-        target = nodes.target("", "", ids=[anchor(package)])
-        self.state.document.note_explicit_target(target)
-        domain.data["objects"][package] = (self.env.docname, anchor(package), "package")
+        target = anchor(package)
+        # Javadoc's package pages open with this declaration; as an object description,
+        # the package's notes and fields look like those of its types in every theme.
+        desc = addnodes.desc(
+            "",
+            domain="java",
+            objtype="package",
+            desctype="package",
+            classes=["java", "package"],
+        )
+        sig = addnodes.desc_signature("", "", ids=[target], fullname=package)
+        sig += addnodes.desc_sig_keyword("package", "package")
+        sig += addnodes.desc_sig_space()
+        sig += addnodes.desc_name(package, package)
+        self.state.document.note_explicit_target(sig)
+        desc += sig
+        desc += addnodes.desc_content("", *documentation(element, self.get_location()))
+        domain.data["objects"][package] = (self.env.docname, target, "package")
         index = addnodes.index(
-            entries=[("single", f"{package} (Java package)", anchor(package), "", None)]
+            entries=[("single", f"{package} (Java package)", target, "", None)]
         )
-        return [index, target, *documentation(element, self.get_location())]
+        return [index, desc]
 
 
 class AutoSummary(JavaDirective):

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/src/sphinx_java_autodoc/extractor.py

@@ -16,7 +16,7 @@ from sphinx.errors import ExtensionError
 
 from .model import Model, read_model
 
-VERSION = "0.4.0"  # x-release-please-version
+VERSION = "0.5.0"  # x-release-please-version
 DOCLET = Path(__file__).parent / "java" / "SphinxDoclet.java"
 PACKAGE = re.compile(r"[^\W\d]\w*(?:\.[^\W\d]\w*)*")
 

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/tests/test_integration.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 from pathlib import Path
+import re
 import shutil
 import subprocess
 import sys
@@ -142,6 +143,30 @@ def test_semantic_extraction(model):
     )
 
 
+def test_package_page_declares_the_package(site):
+    _, out = site
+    package = (out / "api/package-demo.html").read_text()
+    # Like Javadoc, the package page declares the package; its notes sit in the description.
+    declaration = re.search(r'<dl class="java package">(.*?)</dl>', package, re.S)[1]
+    assert f'id="{anchor("demo")}"' in declaration and "Example API." in declaration
+
+
+def test_anchors_are_readable_and_unique(site):
+    _, out = site
+    assert anchor("demo.Widget#convert(int)") == "java:demo.Widget-convert(int)"
+    assert anchor("demo.Widget#<init>(java.lang.String)") == (
+        "java:demo.Widget-new(java.lang.String)"
+    )
+    widget = (out / "api/type-demo.Widget.html").read_text()
+    assert 'id="java:demo.Widget-new(java.lang.String)"' in widget
+    # The package's anchor must not clash with the section ID docutils derives from its title.
+    package = (out / "api/package-demo.html").read_text()
+    assert 'id="java:demo"' in package and 'id="demo"' in package
+    for page in (out / "api").glob("*.html"):
+        ids = re.findall(r'\sid="([^"]+)"', page.read_text())
+        assert len(ids) == len(set(ids)), page.name
+
+
 def test_html_links_structure_inventory_search(site):
     docs, out = site
     html = (out / "api/type-demo.Widget.html").read_text()

{sphinx_java_autodoc-0.4.0 → sphinx_java_autodoc-0.5.0}/tests/visual_check.py

@@ -63,14 +63,25 @@ def main():
                             theme_width,
                             page.evaluate("document.documentElement.scrollWidth"),
                         )
+                    # Anchors contain ":" and "(", which theme scripts must accept.
                     page.goto(
-                        base + "/api/type-demo.Widget.html", wait_until="networkidle"
+                        base
+                        + "/api/type-demo.Widget.html#java:demo.Widget-convert(int)",
+                        wait_until="networkidle",
+                    )
+                    # Some themes scroll smoothly; wait until the target is in view.
+                    page.wait_for_function(
+                        """() => {
+                          const id = decodeURIComponent(location.hash.slice(1));
+                          const top = document.getElementById(id).getBoundingClientRect().top;
+                          return top > -1 && top < innerHeight;
+                        }"""
                     )
                     assert page.locator("dl.java").count() >= 8
                     assert page.locator("h2", has_text="Constructors").count() == 1
                     assert page.locator("pre").count() > 0
                     assert page.locator("dl.java ul li ol li").count() == 2
-                    assert page.locator('a[href^="#java-"]').count() > 0
+                    assert page.locator('a[href^="#java:"]').count() > 0
                     lines = page.locator("dl.java .line-block > .line")
                     assert lines.all_text_contents() == [
                         "First line",