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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,145 +3,22 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import hashlib
6
- import json
7
6
  from pathlib import Path
8
- import re
7
+ import xml.etree.ElementTree as ET
9
8
 
10
9
  from sphinx.errors import ExtensionError
10
+ from sphinx.ext.linkcode import add_linkcode_domain
11
11
  from sphinx.util import logging
12
12
 
13
13
  from .domain import JavaDomain
14
- from .extractor import VERSION, atomic_write, extract
14
+ from .extractor import VERSION, extract
15
15
  from .javadoc import check_mapping
16
- from .model import (
17
- MEMBER_GROUPS,
18
- TYPE_GROUPS,
19
- grouped,
20
- local_name,
21
- read_model,
22
- use_model,
23
- visible,
24
- )
16
+ from .model import Model, read_model, use_model
17
+ from .pages import plan_pages, publish_pages
25
18
  from .render import quiet_reference
26
19
 
27
20
  __version__ = VERSION
28
21
  LOGGER = logging.getLogger(__name__)
29
- MARKER = ".. Generated by sphinx-java-autodoc; do not edit.\n\n"
30
-
31
-
32
- def heading(title: str, underline: str) -> str:
33
- return f"{title}\n{underline * len(title)}\n\n"
34
-
35
-
36
- def summary_table(symbols) -> str:
37
- return ".. java:autosummary::\n\n" + "".join(f" {s}\n" for s in symbols) + "\n"
38
-
39
-
40
- def generate_pages(root, directory: Path, visibility: str) -> None:
41
- pages = {}
42
- entries = []
43
- for package in root.findall("package"):
44
- name = package.get("name", "")
45
- if not re.fullmatch(r"[\w.$]*", name):
46
- raise ExtensionError(f"Java autodoc: invalid package name {name!r}")
47
- types = [
48
- t
49
- for t in root.findall("type")
50
- if t.get("package") == name and visible(t, visibility)
51
- ]
52
- if not types:
53
- continue
54
- filename = "package-" + (name or "default")
55
- entries.append((name, filename))
56
- title = name or "Default package"
57
- body = heading(title, "=")
58
- if name:
59
- body += f".. java:autopackage:: {name}\n\n"
60
- for kind, group in TYPE_GROUPS.items():
61
- symbols = [t.get("id") for t in types if t.get("kind") == kind]
62
- if symbols:
63
- body += heading(group, "-") + summary_table(symbols)
64
- body += ".. toctree::\n :hidden:\n\n"
65
- for t in types:
66
- symbol = t.get("id")
67
- if not re.fullmatch(r"[\w.$]+", symbol):
68
- raise ExtensionError(f"Java autodoc: invalid type name {symbol!r}")
69
- typefile = "type-" + symbol
70
- body += f" {typefile}\n"
71
- # Titles drop the package, which the sidebar and the signature already show.
72
- page = heading(local_name(t), "=") + f".. java:autoclass:: {symbol}\n\n"
73
- members = [m for m in t.findall("member") if visible(m, visibility)]
74
- for group, found in grouped(members).items():
75
- symbols = [m.get("id") for m in found]
76
- directive = "autofield" if group == "field" else "automethod"
77
- page += heading(MEMBER_GROUPS[group], "-") + summary_table(symbols)
78
- page += "".join(f".. java:{directive}:: {s}\n\n" for s in symbols)
79
- pages[typefile + ".rst"] = MARKER + page
80
- pages[filename + ".rst"] = MARKER + body
81
- named = [name for name, _ in entries if name]
82
- pages["index.rst"] = (
83
- MARKER
84
- + heading("Java API", "=")
85
- + (summary_table(named) if named else "")
86
- # The summary cannot list the unnamed package, so then the toctree shows.
87
- + (
88
- ".. toctree::\n :hidden:\n\n"
89
- if len(named) == len(entries)
90
- else ".. toctree::\n\n"
91
- )
92
- + "".join(f" {filename}\n" for _, filename in entries)
93
- )
94
- manifest_path = directory / ".java-autodoc-manifest.json"
95
- try:
96
- old = json.loads(manifest_path.read_text()) if manifest_path.exists() else {}
97
- if not isinstance(old, dict):
98
- raise ValueError("expected a filename-to-hashes mapping")
99
- for filename, hashes in old.items():
100
- if isinstance(hashes, str):
101
- hashes = old[filename] = [hashes]
102
- if (
103
- Path(filename).name != filename
104
- or not filename.endswith(".rst")
105
- or not isinstance(hashes, list)
106
- or not hashes
107
- or any(
108
- not isinstance(h, str) or not re.fullmatch(r"[0-9a-f]{64}", h)
109
- for h in hashes
110
- )
111
- ):
112
- raise ValueError("invalid filename or content hash")
113
- except (OSError, ValueError) as exc:
114
- raise ExtensionError(
115
- f"Java autodoc: invalid generated-page manifest: {exc}"
116
- ) from exc
117
- # Check ownership before recording any new files as ours.
118
- for filename in old.keys() | pages.keys():
119
- path = directory / filename
120
- if path.exists() and hashlib.sha256(
121
- path.read_bytes()
122
- ).hexdigest() not in old.get(filename, []):
123
- raise ExtensionError(
124
- f"Java autodoc: refusing to overwrite edited or unowned page {path}; move your edits into a guide."
125
- )
126
- hashes = {
127
- name: hashlib.sha256(content.encode()).hexdigest()
128
- for name, content in pages.items()
129
- }
130
- pending = {name: set(values) for name, values in old.items()}
131
- for name, digest in hashes.items():
132
- pending.setdefault(name, set()).add(digest)
133
- # Journal both versions before any page changes, so an interrupted build can retry.
134
- atomic_write(
135
- manifest_path,
136
- json.dumps(
137
- {name: sorted(values) for name, values in sorted(pending.items())}
138
- ).encode(),
139
- )
140
- for filename, content in pages.items():
141
- atomic_write(directory / filename, content.encode())
142
- for filename in old.keys() - pages.keys():
143
- (directory / filename).unlink(missing_ok=True)
144
- atomic_write(manifest_path, json.dumps(hashes, indent=2, sort_keys=True).encode())
145
22
 
146
23
 
147
24
  def prepare(app):
@@ -156,33 +33,32 @@ def prepare(app):
156
33
  raise ExtensionError("Set either java_sources or java_model, not both.")
157
34
  if config.java_model:
158
35
  path = (base / config.java_model).resolve()
159
- root = read_model(path)
160
- fingerprint = hashlib.sha256(path.read_bytes()).hexdigest()
36
+ model = Model(
37
+ read_model(path), path, hashlib.sha256(path.read_bytes()).hexdigest()
38
+ )
161
39
  elif config.java_sources:
162
40
  cache = Path(app.doctreedir) / "java-cache"
163
- path, fingerprint = extract(
41
+ model = extract(
164
42
  [base / s for s in config.java_sources],
165
43
  [base / s for s in config.java_classpath],
166
44
  cache,
167
45
  jdk=config.java_jdk,
168
46
  release=str(config.java_release),
169
47
  sourcepath=[base / s for s in config.java_sourcepath],
48
+ encoding=config.java_encoding,
49
+ exclude_packages=config.java_exclude_packages,
170
50
  )
171
- root = read_model(path)
172
51
  # This cache belongs to one doctree directory, so only the current model is kept.
173
52
  for old in cache.glob("*.xml"):
174
- if old != path:
53
+ if old != model.path:
175
54
  old.unlink(missing_ok=True)
176
55
  else:
177
56
  # A consumer using only Java roles and intersphinx needs no local sources.
178
- import xml.etree.ElementTree as ET
179
-
180
- root = ET.Element("api", schema="1")
181
- path = base / "conf.py"
182
- fingerprint = "empty"
183
- app._java_changed = getattr(app.env, "java_fingerprint", None) != fingerprint
184
- app.env.java_fingerprint = fingerprint
185
- app.env.java_model_path = str(path)
57
+ model = Model(ET.Element("api", schema="1"), base / "conf.py", "empty")
58
+ root = model.root
59
+ app._java_changed = getattr(app.env, "java_fingerprint", None) != model.fingerprint
60
+ app.env.java_fingerprint = model.fingerprint
61
+ app.env.java_model_path = str(model.path)
186
62
  use_model(root)
187
63
  for diagnostic in root.findall("diagnostic"):
188
64
  LOGGER.warning(diagnostic.text, type="java", subtype="extract")
@@ -199,7 +75,7 @@ def prepare(app):
199
75
  raise ExtensionError(
200
76
  "Java autodoc: cannot generate API pages without extracted types."
201
77
  )
202
- generate_pages(root, directory, config.java_visibility)
78
+ publish_pages(directory, plan_pages(root, config.java_visibility))
203
79
 
204
80
 
205
81
  def outdated(app, env, added, changed, removed):
@@ -216,6 +92,8 @@ def setup(app):
216
92
  "java_sources": [],
217
93
  "java_classpath": [],
218
94
  "java_sourcepath": [],
95
+ "java_encoding": "UTF-8",
96
+ "java_exclude_packages": [],
219
97
  "java_jdk": "",
220
98
  "java_release": "",
221
99
  "java_model": "",
@@ -226,6 +104,7 @@ def setup(app):
226
104
  }.items():
227
105
  app.add_config_value(name, default, "env")
228
106
  app.add_domain(JavaDomain)
107
+ add_linkcode_domain("java", ["fullname", "source", "line"])
229
108
  app.add_css_file("java-autodoc.css")
230
109
  app.connect("builder-inited", add_static_path)
231
110
  app.connect("builder-inited", prepare)
@@ -8,7 +8,6 @@ import sys
8
8
  from sphinx.errors import ExtensionError
9
9
 
10
10
  from .extractor import atomic_write, extract
11
- from .model import read_model
12
11
 
13
12
 
14
13
  def main():
@@ -32,6 +31,15 @@ def main():
32
31
  type=Path,
33
32
  help="Source lookup directory for ancestor docs; repeat for multiple roots",
34
33
  )
34
+ parser.add_argument(
35
+ "--encoding", default="UTF-8", help="Java source file encoding (default: UTF-8)"
36
+ )
37
+ parser.add_argument(
38
+ "--exclude-package",
39
+ action="append",
40
+ default=[],
41
+ help="Package to omit with its subpackages; repeat for multiple packages",
42
+ )
35
43
  parser.add_argument("--jdk", default="", help="JDK 25 home (default: java on PATH)")
36
44
  parser.add_argument(
37
45
  "--release", default="", help="Source/API release accepted by the installed JDK"
@@ -43,20 +51,22 @@ def main():
43
51
  cp = args.classpath
44
52
  if args.classpath_file:
45
53
  cp += os.pathsep + args.classpath_file.read_text(encoding="utf-8").strip()
46
- path, _ = extract(
54
+ model = extract(
47
55
  args.sources,
48
56
  [Path(p) for p in cp.split(os.pathsep) if p],
49
57
  args.cache,
50
58
  jdk=args.jdk,
51
59
  release=args.release,
52
60
  sourcepath=args.sourcepath,
61
+ encoding=args.encoding,
62
+ exclude_packages=args.exclude_package,
53
63
  )
54
- diagnostics = read_model(path).findall("diagnostic")
64
+ diagnostics = model.root.findall("diagnostic")
55
65
  for diagnostic in diagnostics:
56
66
  print("warning: " + (diagnostic.text or ""), file=sys.stderr)
57
67
  if diagnostics and args.warnings_as_errors:
58
68
  return 1
59
- atomic_write(args.output, path.read_bytes())
69
+ atomic_write(args.output, model.path.read_bytes())
60
70
  except (ExtensionError, OSError) as exc:
61
71
  print(str(exc), file=sys.stderr)
62
72
  return 1
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ from pathlib import PurePosixPath
3
4
  import re
4
5
 
5
6
  from docutils import nodes
@@ -129,7 +130,18 @@ class JavaDirective(SphinxDirective):
129
130
  desc = addnodes.desc(
130
131
  "", domain="java", objtype=role, desctype=role, classes=["java", role]
131
132
  )
132
- sig = addnodes.desc_signature("", "", fullname=symbol)
133
+ package = element.get("package")
134
+ local = symbol.removeprefix(f"{package}.") if package else symbol
135
+ top = local.split("#")[0].split(".")[0]
136
+ # javac requires a public top-level type to live in a file named after it.
137
+ source = PurePosixPath(*package.split("."), f"{top}.java")
138
+ sig = addnodes.desc_signature(
139
+ "",
140
+ "",
141
+ fullname=symbol,
142
+ source=str(source),
143
+ line=element.get("line", ""),
144
+ )
133
145
  sig.extend(signature_nodes(element.find("sig")))
134
146
  limit = (
135
147
  self.config.java_maximum_signature_line_length
@@ -6,6 +6,7 @@ import hashlib
6
6
  import json
7
7
  import os
8
8
  from pathlib import Path
9
+ import re
9
10
  import shutil
10
11
  import subprocess
11
12
  import tempfile
@@ -13,10 +14,11 @@ import xml.etree.ElementTree as ET
13
14
 
14
15
  from sphinx.errors import ExtensionError
15
16
 
16
- from .model import read_model
17
+ from .model import Model, read_model
17
18
 
18
- VERSION = "0.2.0" # x-release-please-version
19
+ VERSION = "0.3.0" # x-release-please-version
19
20
  DOCLET = Path(__file__).parent / "java" / "SphinxDoclet.java"
21
+ PACKAGE = re.compile(r"[^\W\d]\w*(?:\.[^\W\d]\w*)*")
20
22
 
21
23
 
22
24
  def run(arguments: list[str], *, cwd: Path | None = None) -> str:
@@ -67,11 +69,19 @@ def extract(
67
69
  jdk: str = "",
68
70
  release: str = "",
69
71
  sourcepath: list[Path] | None = None,
70
- ) -> tuple[Path, str]:
71
- """Return immutable XML path and input fingerprint. All inputs are content hashed."""
72
+ encoding: str = "UTF-8",
73
+ exclude_packages: list[str] | None = None,
74
+ ) -> Model:
75
+ """Returns the validated model, cached by a content hash of all inputs."""
72
76
  roots = [p.resolve() for p in sources]
73
77
  dependencies = [p.resolve() for p in classpath]
74
78
  lookup = [p.resolve() for p in sourcepath or []]
79
+ excluded = sorted(set(exclude_packages or []))
80
+ for name in excluded:
81
+ if not PACKAGE.fullmatch(name):
82
+ raise ExtensionError(
83
+ f"Java autodoc: excluded package is not a package name: {name!r}"
84
+ )
75
85
  for path in lookup:
76
86
  if not path.is_dir():
77
87
  raise ExtensionError(
@@ -147,6 +157,8 @@ def extract(
147
157
  [str(p) for p in roots],
148
158
  [str(p) for p in dependencies],
149
159
  [str(p) for p in lookup],
160
+ encoding,
161
+ excluded,
150
162
  ]
151
163
  ).encode()
152
164
  )
@@ -171,8 +183,7 @@ def extract(
171
183
  cache.mkdir(parents=True, exist_ok=True)
172
184
  destination = cache / f"{fingerprint}.xml"
173
185
  if destination.exists():
174
- read_model(destination)
175
- return destination, fingerprint
186
+ return Model(read_model(destination), destination, fingerprint)
176
187
  with tempfile.TemporaryDirectory(prefix="extract-", dir=cache) as directory:
177
188
  work = Path(directory)
178
189
  classes = work / "classes"
@@ -193,7 +204,7 @@ def extract(
193
204
  "en_US",
194
205
  "-quiet",
195
206
  "-encoding",
196
- "UTF-8",
207
+ encoding,
197
208
  "-protected",
198
209
  "-doclet",
199
210
  "sphinxjava.SphinxDoclet",
@@ -204,6 +215,8 @@ def extract(
204
215
  ]
205
216
  if release:
206
217
  args += ["--release", str(release)]
218
+ if excluded:
219
+ args += ["--sphinx-exclude", ",".join(excluded)]
207
220
  # An explicit empty classpath avoids implicitly reading classes from cwd.
208
221
  empty = work / "empty"
209
222
  empty.mkdir()
@@ -251,4 +264,4 @@ def extract(
251
264
  atomic_write(
252
265
  destination, ET.tostring(root, encoding="utf-8", xml_declaration=True)
253
266
  )
254
- return destination, fingerprint
267
+ return Model(root, destination, fingerprint)
@@ -5,6 +5,7 @@ import com.sun.source.util.DocTreePath;
5
5
  import com.sun.source.util.DocTrees;
6
6
  import java.nio.file.*;
7
7
  import java.util.*;
8
+ import java.util.function.Consumer;
8
9
  import java.util.regex.Pattern;
9
10
  import java.util.stream.Collectors;
10
11
  import javax.lang.model.SourceVersion;
@@ -22,6 +23,17 @@ import jdk.javadoc.doclet.*;
22
23
  /** Extracts source declarations and semantic documentation using public JDK APIs. */
23
24
  public final class SphinxDoclet implements Doclet {
24
25
  private static final String THROWS = "throws:";
26
+ // JDK-style notes, as named by the JDK's own -tag options.
27
+ private static final Set<String> NOTES = Set.of("apiNote", "implSpec", "implNote");
28
+ // The standard doclet omits these without -author, -version or a serialized-form page.
29
+ private static final Set<DocTree.Kind> OMITTED =
30
+ EnumSet.of(
31
+ DocTree.Kind.HIDDEN,
32
+ DocTree.Kind.AUTHOR,
33
+ DocTree.Kind.VERSION,
34
+ DocTree.Kind.SERIAL,
35
+ DocTree.Kind.SERIAL_DATA,
36
+ DocTree.Kind.SERIAL_FIELD);
25
37
  // shortcut: conservatively detect markup comments; replace with a markup parser when
26
38
  // supporting regions/actions.
27
39
  private static final Pattern SNIPPET_MARKUP =
@@ -32,6 +44,7 @@ public final class SphinxDoclet implements Doclet {
32
44
  private Elements elements;
33
45
  private Types types;
34
46
  private Path output;
47
+ private List<String> excluded = List.of();
35
48
  private final Set<String> warnings = new TreeSet<>();
36
49
  private final Map<Element, Map<String, Part>> comments = new HashMap<>();
37
50
 
@@ -108,41 +121,54 @@ public final class SphinxDoclet implements Doclet {
108
121
  return SourceVersion.latestSupported();
109
122
  }
110
123
 
111
- @Override
112
- public Set<? extends Option> getSupportedOptions() {
113
- return Set.of(
114
- new Option() {
115
- @Override
116
- public int getArgumentCount() {
117
- return 1;
118
- }
124
+ /** A doclet option taking one argument. */
125
+ private record Flag(String name, String parameters, String description, Consumer<String> action)
126
+ implements Option {
127
+ @Override
128
+ public int getArgumentCount() {
129
+ return 1;
130
+ }
119
131
 
120
- @Override
121
- public String getDescription() {
122
- return "Write versioned Sphinx API XML";
123
- }
132
+ @Override
133
+ public String getDescription() {
134
+ return description;
135
+ }
124
136
 
125
- @Override
126
- public Kind getKind() {
127
- return Kind.STANDARD;
128
- }
137
+ @Override
138
+ public Kind getKind() {
139
+ return Kind.STANDARD;
140
+ }
129
141
 
130
- @Override
131
- public List<String> getNames() {
132
- return List.of("--sphinx-output");
133
- }
142
+ @Override
143
+ public List<String> getNames() {
144
+ return List.of(name);
145
+ }
134
146
 
135
- @Override
136
- public String getParameters() {
137
- return "file";
138
- }
147
+ @Override
148
+ public String getParameters() {
149
+ return parameters;
150
+ }
139
151
 
140
- @Override
141
- public boolean process(String name, List<String> arguments) {
142
- output = Path.of(arguments.getFirst());
143
- return true;
144
- }
145
- });
152
+ @Override
153
+ public boolean process(String option, List<String> arguments) {
154
+ action.accept(arguments.getFirst());
155
+ return true;
156
+ }
157
+ }
158
+
159
+ @Override
160
+ public Set<? extends Option> getSupportedOptions() {
161
+ return Set.of(
162
+ new Flag(
163
+ "--sphinx-output",
164
+ "file",
165
+ "Write versioned Sphinx API XML",
166
+ argument -> output = Path.of(argument)),
167
+ new Flag(
168
+ "--sphinx-exclude",
169
+ "packages",
170
+ "Comma-separated packages to omit, with their subpackages",
171
+ argument -> excluded = List.of(argument.split(","))));
146
172
  }
147
173
 
148
174
  @Override
@@ -164,6 +190,7 @@ public final class SphinxDoclet implements Doclet {
164
190
  env.getIncludedElements().stream()
165
191
  .filter(e -> e instanceof TypeElement && visible(e, false) && !hidden(e))
166
192
  .map(TypeElement.class::cast)
193
+ .filter(t -> !excluded(elements.getPackageOf(t).getQualifiedName().toString()))
167
194
  .sorted(Comparator.comparing(t -> t.getQualifiedName().toString()))
168
195
  .toList();
169
196
  var packages = new TreeMap<String, PackageElement>();
@@ -182,6 +209,13 @@ public final class SphinxDoclet implements Doclet {
182
209
  .sorted(Comparator.comparing(this::id))
183
210
  .forEach(member -> declaration(node, "member", member));
184
211
  }
212
+ for (var pkg : excluded) {
213
+ if (env.getIncludedElements().stream()
214
+ .noneMatch(
215
+ e -> excluded(pkg, elements.getPackageOf(e).getQualifiedName().toString()))) {
216
+ warnings.add("Excluded package %s matches no source package.".formatted(pkg));
217
+ }
218
+ }
185
219
  warnings.forEach(warning -> root.addText("diagnostic", warning));
186
220
  var transformer = TransformerFactory.newInstance().newTransformer();
187
221
  transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");
@@ -194,6 +228,15 @@ public final class SphinxDoclet implements Doclet {
194
228
  }
195
229
  }
196
230
 
231
+ private boolean excluded(String pkg) {
232
+ return excluded.stream().anyMatch(prefix -> excluded(prefix, pkg));
233
+ }
234
+
235
+ /** Javadoc -exclude semantics: the package itself and its subpackages. */
236
+ private static boolean excluded(String prefix, String pkg) {
237
+ return pkg.equals(prefix) || pkg.startsWith(prefix + ".");
238
+ }
239
+
197
240
  /** Whether the declaration and all enclosing declarations are public (or protected). */
198
241
  private static boolean visible(Element e, boolean publicOnly) {
199
242
  while (e instanceof TypeElement
@@ -493,6 +536,15 @@ public final class SphinxDoclet implements Doclet {
493
536
  .set("kind", e.getKind().name().toLowerCase(Locale.ROOT))
494
537
  .set("visibility", visible(e, true) ? "public" : "protected")
495
538
  .set("package", elements.getPackageOf(e).getQualifiedName().toString());
539
+ // The line lets sphinx.ext.linkcode link to the source; generated members have none.
540
+ var path = trees.getPath(e);
541
+ if (path != null) {
542
+ var unit = path.getCompilationUnit();
543
+ long start = trees.getSourcePositions().getStartPosition(unit, path.getLeaf());
544
+ if (start >= 0) {
545
+ node.set("line", Long.toString(unit.getLineMap().getLineNumber(start)));
546
+ }
547
+ }
496
548
  sig(node, e);
497
549
  documentation(node, e);
498
550
  return node;
@@ -525,6 +577,7 @@ public final class SphinxDoclet implements Doclet {
525
577
  }
526
578
  }
527
579
  int see = 0;
580
+ int note = 0;
528
581
  for (var tag : comment.getBlockTags()) {
529
582
  switch (tag) {
530
583
  case ParamTree param -> putParam(result, e, param);
@@ -533,8 +586,10 @@ public final class SphinxDoclet implements Doclet {
533
586
  case SeeTree s -> result.put("see:" + see++, new Part(e, "", s.getReference()));
534
587
  case SinceTree since -> result.put("since", new Part(e, "", since.getBody()));
535
588
  case DeprecatedTree d -> result.put("deprecated", new Part(e, "", d.getBody()));
589
+ case UnknownBlockTagTree custom when NOTES.contains(custom.getTagName()) ->
590
+ result.put(custom.getTagName() + ":" + note++, new Part(e, "", custom.getContent()));
536
591
  default -> {
537
- if (tag.getKind() != DocTree.Kind.HIDDEN) {
592
+ if (!OMITTED.contains(tag.getKind())) {
538
593
  warn(e, "Unsupported block tag %s; retain it in handwritten guides.", tag.getKind());
539
594
  }
540
595
  }
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from pathlib import Path
6
6
  import re
7
+ from typing import NamedTuple
7
8
  import xml.etree.ElementTree as ET
8
9
 
9
10
  from sphinx.errors import ExtensionError
@@ -28,6 +29,14 @@ PACKAGES: dict[str, ET.Element] = {}
28
29
  REFERENCES: dict[str, dict[str, str]] = {}
29
30
 
30
31
 
32
+ class Model(NamedTuple):
33
+ """A validated model, the file it came from and the fingerprint of its inputs."""
34
+
35
+ root: ET.Element
36
+ path: Path
37
+ fingerprint: str
38
+
39
+
31
40
  def read_model(path: Path) -> ET.Element:
32
41
  """Validates XML schema 1 at the process boundary and returns its root."""
33
42
  try:
@@ -58,6 +67,8 @@ def read_model(path: Path) -> ET.Element:
58
67
  ids.add(node.attrib["id"])
59
68
  if node.get("visibility") not in {"public", "protected"}:
60
69
  raise ValueError("invalid visibility")
70
+ if not re.fullmatch(r"[1-9]\d*", node.get("line", "1")):
71
+ raise ValueError("invalid line")
61
72
  symbol, name, kind, package = (
62
73
  node.get(key) for key in ("id", "name", "kind", "package")
63
74
  )
@@ -0,0 +1,140 @@
1
+ """Generated API pages: RST skeletons planned from the model and published safely."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ from pathlib import Path
8
+ import re
9
+
10
+ from sphinx.errors import ExtensionError
11
+
12
+ from .extractor import atomic_write
13
+ from .model import MEMBER_GROUPS, TYPE_GROUPS, grouped, local_name, visible
14
+
15
+ MARKER = ".. Generated by sphinx-java-autodoc; do not edit.\n\n"
16
+
17
+
18
+ def heading(title: str, underline: str) -> str:
19
+ return f"{title}\n{underline * len(title)}\n\n"
20
+
21
+
22
+ def summary_table(symbols) -> str:
23
+ return ".. java:autosummary::\n\n" + "".join(f" {s}\n" for s in symbols) + "\n"
24
+
25
+
26
+ def plan_pages(root, visibility: str) -> dict[str, str]:
27
+ """Generated page skeletons by filename, without touching the filesystem."""
28
+ pages = {}
29
+ entries = []
30
+ for package in root.findall("package"):
31
+ name = package.get("name", "")
32
+ if not re.fullmatch(r"[\w.$]*", name):
33
+ raise ExtensionError(f"Java autodoc: invalid package name {name!r}")
34
+ types = [
35
+ t
36
+ for t in root.findall("type")
37
+ if t.get("package") == name and visible(t, visibility)
38
+ ]
39
+ if not types:
40
+ continue
41
+ filename = "package-" + (name or "default")
42
+ entries.append((name, filename))
43
+ title = name or "Default package"
44
+ body = heading(title, "=")
45
+ if name:
46
+ body += f".. java:autopackage:: {name}\n\n"
47
+ for kind, group in TYPE_GROUPS.items():
48
+ symbols = [t.get("id") for t in types if t.get("kind") == kind]
49
+ if symbols:
50
+ body += heading(group, "-") + summary_table(symbols)
51
+ body += ".. toctree::\n :hidden:\n\n"
52
+ for t in types:
53
+ symbol = t.get("id")
54
+ if not re.fullmatch(r"[\w.$]+", symbol):
55
+ raise ExtensionError(f"Java autodoc: invalid type name {symbol!r}")
56
+ typefile = "type-" + symbol
57
+ body += f" {typefile}\n"
58
+ # Titles drop the package, which the sidebar and the signature already show.
59
+ page = heading(local_name(t), "=") + f".. java:autoclass:: {symbol}\n\n"
60
+ members = [m for m in t.findall("member") if visible(m, visibility)]
61
+ for group, found in grouped(members).items():
62
+ symbols = [m.get("id") for m in found]
63
+ directive = "autofield" if group == "field" else "automethod"
64
+ page += heading(MEMBER_GROUPS[group], "-") + summary_table(symbols)
65
+ page += "".join(f".. java:{directive}:: {s}\n\n" for s in symbols)
66
+ pages[typefile + ".rst"] = MARKER + page
67
+ pages[filename + ".rst"] = MARKER + body
68
+ named = [name for name, _ in entries if name]
69
+ pages["index.rst"] = (
70
+ MARKER
71
+ + heading("Java API", "=")
72
+ + (summary_table(named) if named else "")
73
+ # The summary cannot list the unnamed package, so then the toctree shows.
74
+ + (
75
+ ".. toctree::\n :hidden:\n\n"
76
+ if len(named) == len(entries)
77
+ else ".. toctree::\n\n"
78
+ )
79
+ + "".join(f" {filename}\n" for _, filename in entries)
80
+ )
81
+ return pages
82
+
83
+
84
+ def publish_pages(directory: Path, pages: dict[str, str]) -> None:
85
+ """Replaces previously published pages in ``directory`` with ``pages``.
86
+
87
+ Edited or unowned files are never overwritten, and a manifest journals each
88
+ publication so an interrupted build recovers on the next run.
89
+ """
90
+ manifest_path = directory / ".java-autodoc-manifest.json"
91
+ try:
92
+ old = json.loads(manifest_path.read_text()) if manifest_path.exists() else {}
93
+ if not isinstance(old, dict):
94
+ raise ValueError("expected a filename-to-hashes mapping")
95
+ for filename, hashes in old.items():
96
+ if isinstance(hashes, str):
97
+ hashes = old[filename] = [hashes]
98
+ if (
99
+ Path(filename).name != filename
100
+ or not filename.endswith(".rst")
101
+ or not isinstance(hashes, list)
102
+ or not hashes
103
+ or any(
104
+ not isinstance(h, str) or not re.fullmatch(r"[0-9a-f]{64}", h)
105
+ for h in hashes
106
+ )
107
+ ):
108
+ raise ValueError("invalid filename or content hash")
109
+ except (OSError, ValueError) as exc:
110
+ raise ExtensionError(
111
+ f"Java autodoc: invalid generated-page manifest: {exc}"
112
+ ) from exc
113
+ # Check ownership before recording any new files as ours.
114
+ for filename in old.keys() | pages.keys():
115
+ path = directory / filename
116
+ if path.exists() and hashlib.sha256(
117
+ path.read_bytes()
118
+ ).hexdigest() not in old.get(filename, []):
119
+ raise ExtensionError(
120
+ f"Java autodoc: refusing to overwrite edited or unowned page {path}; move your edits into a guide."
121
+ )
122
+ hashes = {
123
+ name: hashlib.sha256(content.encode()).hexdigest()
124
+ for name, content in pages.items()
125
+ }
126
+ pending = {name: set(values) for name, values in old.items()}
127
+ for name, digest in hashes.items():
128
+ pending.setdefault(name, set()).add(digest)
129
+ # Journal both versions before any page changes, so an interrupted build can retry.
130
+ atomic_write(
131
+ manifest_path,
132
+ json.dumps(
133
+ {name: sorted(values) for name, values in sorted(pending.items())}
134
+ ).encode(),
135
+ )
136
+ for filename, content in pages.items():
137
+ atomic_write(directory / filename, content.encode())
138
+ for filename in old.keys() - pages.keys():
139
+ (directory / filename).unlink(missing_ok=True)
140
+ atomic_write(manifest_path, json.dumps(hashes, indent=2, sort_keys=True).encode())
@@ -414,6 +414,10 @@ FIELD_TITLES = {
414
414
  "throws": "Throws",
415
415
  "see": "See also",
416
416
  "since": "Since",
417
+ # The standard doclet's headings for the JDK's custom note tags.
418
+ "apiNote": "API Note",
419
+ "implSpec": "Implementation Requirements",
420
+ "implNote": "Implementation Note",
417
421
  }
418
422
 
419
423
 
@@ -0,0 +1,87 @@
1
+ Metadata-Version: 2.5
2
+ Name: sphinx-java-autodoc
3
+ Version: 0.3.0
4
+ Summary: Compiler-backed Java API documentation in native Sphinx nodes
5
+ Project-URL: Documentation, https://r4sky0.github.io/sphinx-java-autodoc/
6
+ Project-URL: Repository, https://github.com/r4sky0/sphinx-java-autodoc
7
+ Project-URL: Issues, https://github.com/r4sky0/sphinx-java-autodoc/issues
8
+ Project-URL: Changelog, https://github.com/r4sky0/sphinx-java-autodoc/releases
9
+ Author: Ralph Offinger
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: autodoc,documentation,java,javadoc,sphinx
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Framework :: Sphinx :: Extension
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Java
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Documentation :: Sphinx
23
+ Requires-Python: >=3.12
24
+ Requires-Dist: sphinx<9.2,>=9.1
25
+ Provides-Extra: test
26
+ Requires-Dist: build>=1; extra == 'test'
27
+ Requires-Dist: playwright>=1.50; extra == 'test'
28
+ Requires-Dist: pytest>=8; extra == 'test'
29
+ Description-Content-Type: text/markdown
30
+
31
+ # sphinx-java-autodoc
32
+
33
+ [![CI](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml/badge.svg)](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml)
34
+ [![PyPI](https://img.shields.io/pypi/v/sphinx-java-autodoc)](https://pypi.org/project/sphinx-java-autodoc/)
35
+ [Documentation](https://r4sky0.github.io/sphinx-java-autodoc/)
36
+
37
+ Publish your Java library's guides and API reference in one searchable Sphinx
38
+ site. `sphinx-java-autodoc` reads your Java sources and Javadoc comments with the
39
+ JDK compiler APIs and renders them as native Sphinx content:
40
+
41
+ - Generated pages for classes, interfaces, enums, records, annotation types and
42
+ nested types.
43
+ - Signatures, overloads, Javadoc links and inherited method documentation.
44
+ - Class excerpts in handwritten guides, and cross-project links through intersphinx.
45
+ - Content-based caching: pages refresh when sources change.
46
+
47
+ Extraction never runs application classes or annotation processors, and never
48
+ downloads Java dependencies. See the
49
+ [Apache Commons Lang example](https://r4sky0.github.io/sphinx-java-autodoc/showcase/commons-lang/alabaster/)
50
+ for the output.
51
+
52
+ ## Requirements
53
+
54
+ Python 3.12+, Sphinx 9.1.x, and **JDK 25 for extraction**. Your library can keep
55
+ targeting Java 17 or 21. See
56
+ [compatibility and limits](https://r4sky0.github.io/sphinx-java-autodoc/compatibility.html).
57
+
58
+ ## Quick start
59
+
60
+ ```sh
61
+ uv add sphinx-java-autodoc
62
+ ```
63
+
64
+ In `docs/conf.py`:
65
+
66
+ ```python
67
+ extensions = ["sphinx_java_autodoc"]
68
+ java_sources = ["../src/main/java"]
69
+ java_release = "17"
70
+ java_generate = "api"
71
+ java_visibility = "public"
72
+ ```
73
+
74
+ Add `api/index` to the toctree in `docs/index.rst`, then build:
75
+
76
+ ```sh
77
+ uv run sphinx-build -W --keep-going -n docs docs/_build/html
78
+ ```
79
+
80
+ Next: [the first-build walkthrough](https://r4sky0.github.io/sphinx-java-autodoc/getting-started.html),
81
+ [writing guides](https://r4sky0.github.io/sphinx-java-autodoc/guide.html),
82
+ [dependencies and CI](https://r4sky0.github.io/sphinx-java-autodoc/build-integration.html) and the
83
+ [configuration reference](https://r4sky0.github.io/sphinx-java-autodoc/usage.html).
84
+
85
+ ## Development
86
+
87
+ See [CONTRIBUTING.md](CONTRIBUTING.md). [MIT licensed](LICENSE).
@@ -0,0 +1,15 @@
1
+ sphinx_java_autodoc/__init__.py,sha256=tycLGDd1_RKV9xcbYhiqrk1xE8K_uakeUmePTBrc_b8,4387
2
+ sphinx_java_autodoc/__main__.py,sha256=JTMTFP2JYmE-Ii-LOS1UD-ym4GH1YhW6ZZ2CXn-AXWs,2603
3
+ sphinx_java_autodoc/domain.py,sha256=A0yS2Pao4z8PI4dIqTeStEMXATYWXaWodDZB3cGVcyU,14673
4
+ sphinx_java_autodoc/extractor.py,sha256=jhIoHBog78VA8Knsws2oyz3DI6RGmfR7eFJGsalOI1I,9366
5
+ sphinx_java_autodoc/javadoc.py,sha256=p6EDQ-2_tt8YwI4UpM1hyKTF-9WDI79Gl-ukT4DCB4s,1808
6
+ sphinx_java_autodoc/model.py,sha256=kDpGEuh5mImRtcT5a16msxmrGRCAJHfWVytaItqgGt0,7754
7
+ sphinx_java_autodoc/pages.py,sha256=O4jC_NAx-4CTU_a944dO-k0JrPpGYFJOie3iisbenpo,5755
8
+ sphinx_java_autodoc/render.py,sha256=fO7jnq3UrJ2PuNizxzdWw9mLH_baro_q4H8tIkaM-SI,19294
9
+ sphinx_java_autodoc/java/SphinxDoclet.java,sha256=0wBs-oquNWd3ED9eDRvtKz-bSv8cmPvAzvYkxpVgcsc,40236
10
+ sphinx_java_autodoc/static/java-autodoc.css,sha256=ahbn-sRIqh4RQBEJJ0tMmoHtF0RmRO_b8nfJNc1vJl4,694
11
+ sphinx_java_autodoc-0.3.0.dist-info/METADATA,sha256=rkmm4PsN4BB2U_kERjqWOCFh0hsyXqIGhzgMoWZxZHE,3448
12
+ sphinx_java_autodoc-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
13
+ sphinx_java_autodoc-0.3.0.dist-info/entry_points.txt,sha256=WgWf-WcpfeRFC2tcLu7lY0_OF8s_YnB1x-_T4TijaWs,74
14
+ sphinx_java_autodoc-0.3.0.dist-info/licenses/LICENSE,sha256=FE03yeUGD0GeRnHdafTfDp6JJzwDFOYi3xZJHcOQ8zo,1089
15
+ sphinx_java_autodoc-0.3.0.dist-info/RECORD,,
@@ -1,109 +0,0 @@
1
- Metadata-Version: 2.5
2
- Name: sphinx-java-autodoc
3
- Version: 0.2.0
4
- Summary: Compiler-backed Java API documentation in native Sphinx nodes
5
- Project-URL: Documentation, https://r4sky0.github.io/sphinx-java-autodoc/
6
- Project-URL: Repository, https://github.com/r4sky0/sphinx-java-autodoc
7
- Project-URL: Issues, https://github.com/r4sky0/sphinx-java-autodoc/issues
8
- Project-URL: Changelog, https://github.com/r4sky0/sphinx-java-autodoc/releases
9
- Author: Ralph Offinger
10
- License-Expression: MIT
11
- License-File: LICENSE
12
- Keywords: autodoc,documentation,java,javadoc,sphinx
13
- Classifier: Development Status :: 3 - Alpha
14
- Classifier: Framework :: Sphinx :: Extension
15
- Classifier: Intended Audience :: Developers
16
- Classifier: Operating System :: OS Independent
17
- Classifier: Programming Language :: Java
18
- Classifier: Programming Language :: Python :: 3 :: Only
19
- Classifier: Programming Language :: Python :: 3.12
20
- Classifier: Programming Language :: Python :: 3.13
21
- Classifier: Programming Language :: Python :: 3.14
22
- Classifier: Topic :: Documentation :: Sphinx
23
- Requires-Python: >=3.12
24
- Requires-Dist: sphinx<9.2,>=9.1
25
- Provides-Extra: test
26
- Requires-Dist: build>=1; extra == 'test'
27
- Requires-Dist: playwright>=1.50; extra == 'test'
28
- Requires-Dist: pytest>=8; extra == 'test'
29
- Description-Content-Type: text/markdown
30
-
31
- # sphinx-java-autodoc
32
-
33
- [![CI](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml/badge.svg)](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml)
34
- [Documentation](https://r4sky0.github.io/sphinx-java-autodoc/)
35
-
36
- Publish your Java library's guides and API reference in one searchable Sphinx
37
- site. Keep API contracts in Java sources and Javadoc; write guides that help
38
- your users choose an API and complete a task.
39
-
40
- `sphinx-java-autodoc` reads Java sources and Javadoc comments with the JDK compiler
41
- APIs and renders them as native Sphinx content:
42
-
43
- - Generated, searchable pages for classes, interfaces, enums, records, annotation
44
- types and nested types.
45
- - Signatures, overloads, Javadoc links and inherited method documentation.
46
- - Class excerpts in handwritten guides, and links between projects through intersphinx.
47
- - Pages that refresh when sources change, with content-based extraction caching.
48
-
49
- Extraction never executes application classes or annotation processors, and never
50
- downloads Java dependencies. See the [Apache Commons Lang example](https://r4sky0.github.io/sphinx-java-autodoc/showcase/commons-lang/furo/)
51
- for what the output looks like.
52
-
53
- ## Requirements
54
-
55
- Python 3.12+, Sphinx 9.1.x, and **JDK 25 for extraction**. Your library can keep
56
- targeting Java 17 or 21. See [compatibility and limits](https://r4sky0.github.io/sphinx-java-autodoc/compatibility.html)
57
- for the tested versions.
58
-
59
- ## Quick start
60
-
61
- ```sh
62
- uv add "sphinx-java-autodoc @ git+https://github.com/r4sky0/sphinx-java-autodoc.git"
63
- ```
64
-
65
- In `docs/conf.py`:
66
-
67
- ```python
68
- extensions = ["sphinx_java_autodoc"]
69
- java_sources = ["../src/main/java"]
70
- java_release = "17"
71
- java_generate = "api"
72
- java_visibility = "public"
73
- ```
74
-
75
- Add `api/index` to the toctree in `docs/index.rst`, then build:
76
-
77
- ```sh
78
- uv run sphinx-build -W --keep-going -n docs docs/_build/html
79
- ```
80
-
81
- [Publish your first API pages](https://r4sky0.github.io/sphinx-java-autodoc/getting-started.html) walks through these steps.
82
- Then continue with:
83
-
84
- - [Write a guide your users can follow](https://r4sky0.github.io/sphinx-java-autodoc/guide.html)
85
- - [Build with dependencies and CI](https://r4sky0.github.io/sphinx-java-autodoc/build-integration.html): Maven/Gradle
86
- classpaths, pre-extracted models and publishing to GitHub Pages
87
- - [Configuration and reference](https://r4sky0.github.io/sphinx-java-autodoc/usage.html) and [supported Javadoc](https://r4sky0.github.io/sphinx-java-autodoc/javadoc-support.html)
88
- - [Troubleshooting](https://r4sky0.github.io/sphinx-java-autodoc/troubleshooting.html)
89
- - [How it works](https://r4sky0.github.io/sphinx-java-autodoc/design.html) and the [architecture decision](docs/adr/0001-jdk-doclet-xml-sphinx-domain.md)
90
-
91
- ## Development
92
-
93
- From a clone of this repository:
94
-
95
- ```sh
96
- uv sync --locked
97
- uv run --locked pre-commit install
98
- uv run --locked pre-commit run --all-files
99
- uv run --locked pytest
100
- uv run --locked --group showcase python showcase/build.py
101
- uv run --locked sphinx-build -W --keep-going -n docs docs/_build/html
102
- ```
103
-
104
- Development and releases are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
105
- CI covers lint, compiler warnings, integration tests, built distributions,
106
- dependency vulnerabilities, six HTML themes, the text builder, and Chromium
107
- browser interactions.
108
-
109
- [MIT licensed](LICENSE).
@@ -1,14 +0,0 @@
1
- sphinx_java_autodoc/__init__.py,sha256=pWLjl0U0-OUDs_qgEEX_pv1Aq76aIcArov8hcuQcvsI,9208
2
- sphinx_java_autodoc/__main__.py,sha256=ZoDNKnyOSMsiGv7k6hfZgCEazLyvfiOpd096IFuBAEY,2240
3
- sphinx_java_autodoc/domain.py,sha256=TkpzmvfsgEXoQSaUVaSQ8fx59oSi5Thn-X1Egwdwt5A,14205
4
- sphinx_java_autodoc/extractor.py,sha256=sBBzCSukDeFGqeEUGMGblNnVp8kTMgKnaYCR2Gv_-5o,8847
5
- sphinx_java_autodoc/javadoc.py,sha256=p6EDQ-2_tt8YwI4UpM1hyKTF-9WDI79Gl-ukT4DCB4s,1808
6
- sphinx_java_autodoc/model.py,sha256=DvJEi4Q6C1wcpOo-3ym0l8PaKxPncEL3FXJuWzQZslY,7435
7
- sphinx_java_autodoc/render.py,sha256=Qduoo4nLpdAKKxFvDiifIKekbn70Jhh4_c-cPsL31wo,19112
8
- sphinx_java_autodoc/java/SphinxDoclet.java,sha256=zMDMq8Spiia6pcGjGa4TGaGr8FCcd7Pl3bKfu7OF8x8,37990
9
- sphinx_java_autodoc/static/java-autodoc.css,sha256=ahbn-sRIqh4RQBEJJ0tMmoHtF0RmRO_b8nfJNc1vJl4,694
10
- sphinx_java_autodoc-0.2.0.dist-info/METADATA,sha256=rFQk3YErqiazmwI-tggotDQWS2RR6S9R3Ch14-GPjC8,4576
11
- sphinx_java_autodoc-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
12
- sphinx_java_autodoc-0.2.0.dist-info/entry_points.txt,sha256=WgWf-WcpfeRFC2tcLu7lY0_OF8s_YnB1x-_T4TijaWs,74
13
- sphinx_java_autodoc-0.2.0.dist-info/licenses/LICENSE,sha256=FE03yeUGD0GeRnHdafTfDp6JJzwDFOYi3xZJHcOQ8zo,1089
14
- sphinx_java_autodoc-0.2.0.dist-info/RECORD,,