sphinx-java-autodoc 0.2.0__py3-none-any.whl

sphinx_java_autodoc/__init__.py

@@ -0,0 +1,239 @@
+"""Java source documentation in Sphinx, without importing application code."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+import re
+
+from sphinx.errors import ExtensionError
+from sphinx.util import logging
+
+from .domain import JavaDomain
+from .extractor import VERSION, atomic_write, extract
+from .javadoc import check_mapping
+from .model import (
+    MEMBER_GROUPS,
+    TYPE_GROUPS,
+    grouped,
+    local_name,
+    read_model,
+    use_model,
+    visible,
+)
+from .render import quiet_reference
+
+__version__ = VERSION
+LOGGER = logging.getLogger(__name__)
+MARKER = ".. Generated by sphinx-java-autodoc; do not edit.\n\n"
+
+
+def heading(title: str, underline: str) -> str:
+    return f"{title}\n{underline * len(title)}\n\n"
+
+
+def summary_table(symbols) -> str:
+    return ".. java:autosummary::\n\n" + "".join(f"   {s}\n" for s in symbols) + "\n"
+
+
+def generate_pages(root, directory: Path, visibility: str) -> None:
+    pages = {}
+    entries = []
+    for package in root.findall("package"):
+        name = package.get("name", "")
+        if not re.fullmatch(r"[\w.$]*", name):
+            raise ExtensionError(f"Java autodoc: invalid package name {name!r}")
+        types = [
+            t
+            for t in root.findall("type")
+            if t.get("package") == name and visible(t, visibility)
+        ]
+        if not types:
+            continue
+        filename = "package-" + (name or "default")
+        entries.append((name, filename))
+        title = name or "Default package"
+        body = heading(title, "=")
+        if name:
+            body += f".. java:autopackage:: {name}\n\n"
+        for kind, group in TYPE_GROUPS.items():
+            symbols = [t.get("id") for t in types if t.get("kind") == kind]
+            if symbols:
+                body += heading(group, "-") + summary_table(symbols)
+        body += ".. toctree::\n   :hidden:\n\n"
+        for t in types:
+            symbol = t.get("id")
+            if not re.fullmatch(r"[\w.$]+", symbol):
+                raise ExtensionError(f"Java autodoc: invalid type name {symbol!r}")
+            typefile = "type-" + symbol
+            body += f"   {typefile}\n"
+            # Titles drop the package, which the sidebar and the signature already show.
+            page = heading(local_name(t), "=") + f".. java:autoclass:: {symbol}\n\n"
+            members = [m for m in t.findall("member") if visible(m, visibility)]
+            for group, found in grouped(members).items():
+                symbols = [m.get("id") for m in found]
+                directive = "autofield" if group == "field" else "automethod"
+                page += heading(MEMBER_GROUPS[group], "-") + summary_table(symbols)
+                page += "".join(f".. java:{directive}:: {s}\n\n" for s in symbols)
+            pages[typefile + ".rst"] = MARKER + page
+        pages[filename + ".rst"] = MARKER + body
+    named = [name for name, _ in entries if name]
+    pages["index.rst"] = (
+        MARKER
+        + heading("Java API", "=")
+        + (summary_table(named) if named else "")
+        # The summary cannot list the unnamed package, so then the toctree shows.
+        + (
+            ".. toctree::\n   :hidden:\n\n"
+            if len(named) == len(entries)
+            else ".. toctree::\n\n"
+        )
+        + "".join(f"   {filename}\n" for _, filename in entries)
+    )
+    manifest_path = directory / ".java-autodoc-manifest.json"
+    try:
+        old = json.loads(manifest_path.read_text()) if manifest_path.exists() else {}
+        if not isinstance(old, dict):
+            raise ValueError("expected a filename-to-hashes mapping")
+        for filename, hashes in old.items():
+            if isinstance(hashes, str):
+                hashes = old[filename] = [hashes]
+            if (
+                Path(filename).name != filename
+                or not filename.endswith(".rst")
+                or not isinstance(hashes, list)
+                or not hashes
+                or any(
+                    not isinstance(h, str) or not re.fullmatch(r"[0-9a-f]{64}", h)
+                    for h in hashes
+                )
+            ):
+                raise ValueError("invalid filename or content hash")
+    except (OSError, ValueError) as exc:
+        raise ExtensionError(
+            f"Java autodoc: invalid generated-page manifest: {exc}"
+        ) from exc
+    # Check ownership before recording any new files as ours.
+    for filename in old.keys() | pages.keys():
+        path = directory / filename
+        if path.exists() and hashlib.sha256(
+            path.read_bytes()
+        ).hexdigest() not in old.get(filename, []):
+            raise ExtensionError(
+                f"Java autodoc: refusing to overwrite edited or unowned page {path}; move your edits into a guide."
+            )
+    hashes = {
+        name: hashlib.sha256(content.encode()).hexdigest()
+        for name, content in pages.items()
+    }
+    pending = {name: set(values) for name, values in old.items()}
+    for name, digest in hashes.items():
+        pending.setdefault(name, set()).add(digest)
+    # Journal both versions before any page changes, so an interrupted build can retry.
+    atomic_write(
+        manifest_path,
+        json.dumps(
+            {name: sorted(values) for name, values in sorted(pending.items())}
+        ).encode(),
+    )
+    for filename, content in pages.items():
+        atomic_write(directory / filename, content.encode())
+    for filename in old.keys() - pages.keys():
+        (directory / filename).unlink(missing_ok=True)
+    atomic_write(manifest_path, json.dumps(hashes, indent=2, sort_keys=True).encode())
+
+
+def prepare(app):
+    config = app.config
+    if config.java_visibility not in {"public", "protected"}:
+        raise ExtensionError(
+            "java_visibility must be 'public' or 'protected' (public plus protected)."
+        )
+    check_mapping(config.java_external_javadoc)
+    base = Path(app.confdir)
+    if config.java_model and config.java_sources:
+        raise ExtensionError("Set either java_sources or java_model, not both.")
+    if config.java_model:
+        path = (base / config.java_model).resolve()
+        root = read_model(path)
+        fingerprint = hashlib.sha256(path.read_bytes()).hexdigest()
+    elif config.java_sources:
+        cache = Path(app.doctreedir) / "java-cache"
+        path, fingerprint = extract(
+            [base / s for s in config.java_sources],
+            [base / s for s in config.java_classpath],
+            cache,
+            jdk=config.java_jdk,
+            release=str(config.java_release),
+            sourcepath=[base / s for s in config.java_sourcepath],
+        )
+        root = read_model(path)
+        # This cache belongs to one doctree directory, so only the current model is kept.
+        for old in cache.glob("*.xml"):
+            if old != path:
+                old.unlink(missing_ok=True)
+    else:
+        # A consumer using only Java roles and intersphinx needs no local sources.
+        import xml.etree.ElementTree as ET
+
+        root = ET.Element("api", schema="1")
+        path = base / "conf.py"
+        fingerprint = "empty"
+    app._java_changed = getattr(app.env, "java_fingerprint", None) != fingerprint
+    app.env.java_fingerprint = fingerprint
+    app.env.java_model_path = str(path)
+    use_model(root)
+    for diagnostic in root.findall("diagnostic"):
+        LOGGER.warning(diagnostic.text, type="java", subtype="extract")
+    if config.java_generate:
+        directory = (Path(app.srcdir) / config.java_generate).resolve()
+        if (
+            not directory.is_relative_to(Path(app.srcdir).resolve())
+            or directory == Path(app.srcdir).resolve()
+        ):
+            raise ExtensionError(
+                "java_generate must be a subdirectory of the Sphinx source directory."
+            )
+        if not root.findall("type"):
+            raise ExtensionError(
+                "Java autodoc: cannot generate API pages without extracted types."
+            )
+        generate_pages(root, directory, config.java_visibility)
+
+
+def outdated(app, env, added, changed, removed):
+    # Roles and missing-type directives also depend on the complete Java model.
+    return sorted(env.found_docs - removed) if app._java_changed else []
+
+
+def add_static_path(app):
+    app.config.html_static_path.append(str(Path(__file__).parent / "static"))
+
+
+def setup(app):
+    for name, default in {
+        "java_sources": [],
+        "java_classpath": [],
+        "java_sourcepath": [],
+        "java_jdk": "",
+        "java_release": "",
+        "java_model": "",
+        "java_generate": "",
+        "java_visibility": "protected",
+        "java_external_javadoc": {},
+        "java_maximum_signature_line_length": None,
+    }.items():
+        app.add_config_value(name, default, "env")
+    app.add_domain(JavaDomain)
+    app.add_css_file("java-autodoc.css")
+    app.connect("builder-inited", add_static_path)
+    app.connect("builder-inited", prepare)
+    app.connect("env-get-outdated", outdated)
+    app.connect("missing-reference", quiet_reference)
+    return {
+        "version": VERSION,
+        "env_version": 4,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_java_autodoc/__main__.py

@@ -0,0 +1,67 @@
+"""Explicit extraction for build systems and JDK-free Sphinx rendering."""
+
+import argparse
+import os
+from pathlib import Path
+import sys
+
+from sphinx.errors import ExtensionError
+
+from .extractor import atomic_write, extract
+from .model import read_model
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "sources", nargs="+", type=Path, help="Java files or source roots"
+    )
+    parser.add_argument("-o", "--output", required=True, type=Path)
+    parser.add_argument(
+        "--classpath", default="", help=f"Compile classpath separated by {os.pathsep!r}"
+    )
+    parser.add_argument(
+        "--classpath-file",
+        type=Path,
+        help="UTF-8 file containing a platform-separated compile classpath",
+    )
+    parser.add_argument(
+        "--sourcepath",
+        action="append",
+        default=[],
+        type=Path,
+        help="Source lookup directory for ancestor docs; repeat for multiple roots",
+    )
+    parser.add_argument("--jdk", default="", help="JDK 25 home (default: java on PATH)")
+    parser.add_argument(
+        "--release", default="", help="Source/API release accepted by the installed JDK"
+    )
+    parser.add_argument("--cache", type=Path, default=Path(".java-autodoc-cache"))
+    parser.add_argument("--warnings-as-errors", action="store_true")
+    args = parser.parse_args()
+    try:
+        cp = args.classpath
+        if args.classpath_file:
+            cp += os.pathsep + args.classpath_file.read_text(encoding="utf-8").strip()
+        path, _ = extract(
+            args.sources,
+            [Path(p) for p in cp.split(os.pathsep) if p],
+            args.cache,
+            jdk=args.jdk,
+            release=args.release,
+            sourcepath=args.sourcepath,
+        )
+        diagnostics = read_model(path).findall("diagnostic")
+        for diagnostic in diagnostics:
+            print("warning: " + (diagnostic.text or ""), file=sys.stderr)
+        if diagnostics and args.warnings_as_errors:
+            return 1
+        atomic_write(args.output, path.read_bytes())
+    except (ExtensionError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sphinx_java_autodoc/domain.py

@@ -0,0 +1,387 @@
+from __future__ import annotations
+
+import re
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.domains import Domain, ObjType
+from sphinx.roles import XRefRole
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import make_refnode
+
+from .javadoc import external_url
+from .model import (
+    MEMBER_GROUPS,
+    PACKAGES,
+    REFERENCES,
+    SYMBOLS,
+    grouped,
+    local_name,
+    member_label,
+    visible,
+)
+from .render import deprecated, documentation, summary
+
+LOGGER = logging.getLogger(__name__)
+
+
+def anchor(symbol: str) -> str:
+    return "java-" + symbol.encode("utf-8").hex()
+
+
+def role_for(element):
+    return (
+        "type"
+        if element.tag == "type"
+        else "method"
+        if element.get("kind") in {"method", "constructor"}
+        else "field"
+    )
+
+
+# Signature tokens from the model mapped to Sphinx's standard signature nodes.
+SIGNATURE_NODES = {
+    "k": addnodes.desc_sig_keyword,
+    "kt": addnodes.desc_sig_keyword_type,
+    "q": addnodes.desc_addname,
+    "n": addnodes.desc_name,
+    "tv": addnodes.desc_sig_name,
+    "pname": addnodes.desc_sig_name,
+}
+
+
+def signature_nodes(tokens) -> list[nodes.Node]:
+    result: list[nodes.Node] = []
+    for token in tokens:
+        text = token.text or ""
+        if token.tag == "params":
+            parameters = addnodes.desc_parameterlist()
+            for parameter in token.findall("param"):
+                parameters += addnodes.desc_parameter(
+                    "", "", *signature_nodes(parameter)
+                )
+            result.append(parameters)
+        elif token.tag == "t":
+            for part in re.split(r"( +)", text):
+                if part:
+                    result.append(
+                        addnodes.desc_sig_space()
+                        if part.isspace()
+                        else addnodes.desc_sig_punctuation("", part)
+                    )
+        elif token.tag == "v":
+            literal = (
+                addnodes.desc_sig_literal_string
+                if text[:1] in {'"', "'"}
+                else addnodes.desc_sig_literal_number
+            )
+            result.append(literal("", text))
+        elif token.tag == "r":
+            # Like type annotations in Sphinx's Python domain, unresolved types stay
+            # plain text and only warn in nitpicky mode.
+            reference = addnodes.pending_xref(
+                "",
+                nodes.Text(text),
+                refdomain="java",
+                reftype="type",
+                reftarget=token.get("target", ""),
+                refexplicit=True,
+                refwarn=False,
+            )
+            reference["java:external"] = dict(token.attrib)
+            result.append(reference)
+        elif token.tag in SIGNATURE_NODES:
+            result.append(SIGNATURE_NODES[token.tag]("", text))
+    return result
+
+
+def display_name(symbol: str) -> str:
+    owner, _, member = symbol.partition("#")
+    return f"{owner}.{member_label(symbol)}" if member else symbol
+
+
+class JavaDirective(SphinxDirective):
+    def visible(self, element) -> bool:
+        return visible(
+            element, self.options.get("visibility", self.config.java_visibility)
+        )
+
+    def lookup(self, symbol, tags=("type", "member")):
+        self.env.note_dependency(self.env.java_model_path)
+        element = SYMBOLS.get(symbol)
+        return element if element is not None and element.tag in tags else None
+
+    def missing(self, what, symbol, subtype):
+        LOGGER.warning(
+            "Java %s %s was not extracted; check java_sources and visibility.",
+            what,
+            symbol,
+            location=self.get_location(),
+            type="java",
+            subtype=subtype,
+        )
+
+    def describe(self, element):
+        symbol = element.get("id")
+        role = role_for(element)
+        desc = addnodes.desc(
+            "", domain="java", objtype=role, desctype=role, classes=["java", role]
+        )
+        sig = addnodes.desc_signature("", "", fullname=symbol)
+        sig.extend(signature_nodes(element.find("sig")))
+        limit = (
+            self.config.java_maximum_signature_line_length
+            or self.config.maximum_signature_line_length
+        )
+        if limit and len(sig.astext()) > limit:
+            for parameters in sig.findall(addnodes.desc_parameterlist):
+                parameters["multi_line_parameter_list"] = True
+        owner, _, member = symbol.partition("#")
+        # Sphinx lists objects in the page's table of contents from these attributes.
+        sig["_toc_parts"] = (owner, member) if member else (owner,)
+        sig["_toc_name"] = member_label(symbol) if member else owner.rpartition(".")[2]
+        result = [desc]
+        if "no-index" not in self.options:
+            target = anchor(symbol)
+            sig["ids"].append(target)
+            self.state.document.note_explicit_target(sig)
+            domain = self.env.get_domain("java")
+            if domain.data["objects"].get(symbol):
+                LOGGER.warning(
+                    "Duplicate Java documentation for %s; use :no-index: on repeated excerpts.",
+                    symbol,
+                    location=self.get_location(),
+                    type="java",
+                    subtype="duplicate",
+                )
+            else:
+                domain.data["objects"][symbol] = (self.env.docname, target, role)
+                where = f" in {owner}" if member else ""
+                entry = f"{sig['_toc_name']} (Java {element.get('kind').replace('_', ' ')}{where})"
+                result.insert(
+                    0, addnodes.index(entries=[("single", entry, target, "", None)])
+                )
+        desc += sig
+        desc += addnodes.desc_content("", *documentation(element, self.get_location()))
+        return result
+
+
+class AutoClass(JavaDirective):
+    required_arguments = 1
+    option_spec = {
+        "members": directives.unchanged,
+        "exclude-members": directives.unchanged,
+        "visibility": lambda v: directives.choice(v, ("public", "protected")),
+        "no-index": directives.flag,
+    }
+
+    def run(self):
+        symbol = self.arguments[0].strip()
+        element = self.lookup(symbol, ("type",))
+        if element is None:
+            self.missing("type", symbol, "type")
+            return []
+        if not self.visible(element):
+            return []
+        result = self.describe(element)
+        if "members" in self.options:
+            # Semicolons allow exact signatures containing commas.
+            selected = {
+                s.strip() for s in self.options["members"].split(";") if s.strip()
+            }
+            excluded = {
+                s.strip()
+                for s in self.options.get("exclude-members", "").split(";")
+                if s.strip()
+            }
+            matched = set()
+            members = []
+            for member in element.findall("member"):
+                names = {member.get("name"), member.get("id").split("#", 1)[1]}
+                if selected and not names & selected:
+                    continue
+                matched.update(names & selected)
+                if names & excluded or not self.visible(member):
+                    continue
+                members.append(member)
+            for missing in sorted(selected - matched):
+                LOGGER.warning(
+                    "Java member %s#%s was not found.",
+                    symbol,
+                    missing,
+                    location=self.get_location(),
+                    type="java",
+                    subtype="member",
+                )
+            content = result[-1][-1]
+            for group, found in grouped(members).items():
+                content += nodes.rubric("", MEMBER_GROUPS[group])
+                for member in found:
+                    content.extend(self.describe(member))
+        return result
+
+
+class AutoMember(JavaDirective):
+    """One method, constructor or field, like autodoc's automethod and autoattribute."""
+
+    required_arguments = 1
+    option_spec = {"no-index": directives.flag}
+
+    def run(self):
+        symbol = re.sub(r"\s+", "", self.arguments[0])
+        element = self.lookup(symbol.replace("...", "[]"), ("member",))
+        if element is None:
+            self.missing("member", symbol, "member")
+            return []
+        return self.describe(element)
+
+
+class AutoPackage(JavaDirective):
+    required_arguments = 1
+
+    def run(self):
+        package = self.arguments[0].strip()
+        self.env.note_dependency(self.env.java_model_path)
+        element = PACKAGES.get(package)
+        if element is None:
+            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")
+        index = addnodes.index(
+            entries=[("single", f"{package} (Java package)", anchor(package), "", None)]
+        )
+        return [index, target, *documentation(element, self.get_location())]
+
+
+class AutoSummary(JavaDirective):
+    """A table of linked names and first sentences, like sphinx.ext.autosummary."""
+
+    has_content = True
+
+    def run(self):
+        self.env.note_dependency(self.env.java_model_path)
+        table = nodes.table("", classes=["autosummary", "longtable", "java"])
+        group = nodes.tgroup("", cols=2)
+        group += nodes.colspec("", colwidth=10)
+        group += nodes.colspec("", colwidth=90)
+        body = nodes.tbody()
+        for line in self.content:
+            symbol = re.sub(r"\s+", "", line)
+            if not symbol:
+                continue
+            element = self.lookup(symbol)
+            if element is not None:
+                label = local_name(element)
+            elif symbol in PACKAGES:
+                element, label = PACKAGES[symbol], symbol
+            else:
+                self.missing("object", symbol, "summary")
+                continue
+            link = addnodes.pending_xref(
+                "",
+                nodes.literal("", label, classes=["xref", "java"]),
+                refdomain="java",
+                reftype="obj",
+                reftarget=symbol,
+                refexplicit=True,
+                refwarn=True,
+            )
+            text = nodes.paragraph("")
+            if deprecated(element):
+                text += [nodes.strong("", "Deprecated."), nodes.Text(" ")]
+            text.extend(summary(element, self.get_location()))
+            body += nodes.row(
+                "",
+                nodes.entry("", nodes.paragraph("", "", link)),
+                nodes.entry("", text),
+            )
+        if not body.children:
+            return []
+        group += body
+        table += group
+        return [table]
+
+
+class JavaDomain(Domain):
+    name = "java"
+    label = "Java"
+    object_types = {
+        name: ObjType(name, name, "obj")
+        for name in ("type", "method", "field", "package")
+    }
+    roles = {
+        name: XRefRole(warn_dangling=True)
+        for name in ("type", "method", "field", "package", "obj")
+    }
+    directives = {
+        "autoclass": AutoClass,
+        "automethod": AutoMember,
+        "autofield": AutoMember,
+        "autopackage": AutoPackage,
+        "autosummary": AutoSummary,
+    }
+    initial_data = {"objects": {}}
+
+    def clear_doc(self, docname):
+        self.data["objects"] = {
+            k: v for k, v in self.data["objects"].items() if v[0] != docname
+        }
+
+    def merge_domaindata(self, docnames, otherdata):
+        for symbol, value in otherdata["objects"].items():
+            if value[0] in docnames:
+                if (
+                    symbol in self.data["objects"]
+                    and self.data["objects"][symbol] != value
+                ):
+                    LOGGER.warning(
+                        "Duplicate Java documentation for %s.",
+                        symbol,
+                        type="java",
+                        subtype="duplicate",
+                    )
+                self.data["objects"][symbol] = value
+
+    def get_objects(self):
+        for symbol, (docname, target, kind) in sorted(self.data["objects"].items()):
+            # Sphinx's search treats the text after the last dot as the object's name,
+            # so members display as Type.member(SimpleTypes); IDs stay canonical.
+            yield symbol, display_name(symbol), kind, docname, target, 0
+
+    def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
+        spelling = re.sub(r"\s+", "", target)
+        target = spelling.replace("...", "[]")
+        objects = self.data["objects"]
+        # Only member names can omit their parameter list.
+        if target not in objects and "#" in target and "(" not in target:
+            matches = [key for key in objects if key.startswith(target + "(")]
+            if len(matches) == 1:
+                target = matches[0]
+            elif len(matches) > 1:
+                LOGGER.warning(
+                    "Ambiguous Java reference %s; include fully qualified parameter types.",
+                    target,
+                    location=node,
+                    type="java",
+                    subtype="ambiguous",
+                )
+                return None
+        if target in objects:
+            docname, ident, kind = objects[target]
+            if typ not in {"obj", kind}:
+                return None
+            return make_refnode(builder, fromdocname, docname, ident, contnode, target)
+        metadata = node.get("java:external") or REFERENCES.get(target, {})
+        url = external_url(target, spelling, metadata, env.config.java_external_javadoc)
+        return nodes.reference("", "", contnode, refuri=url) if url else None
+
+    def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode):
+        resolved = self.resolve_xref(
+            env, fromdocname, builder, "obj", target, node, contnode
+        )
+        return [("java:obj", resolved)] if resolved else []