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.
- sphinx_java_autodoc/__init__.py +21 -142
- sphinx_java_autodoc/__main__.py +14 -4
- sphinx_java_autodoc/domain.py +13 -1
- sphinx_java_autodoc/extractor.py +21 -8
- sphinx_java_autodoc/java/SphinxDoclet.java +86 -31
- sphinx_java_autodoc/model.py +11 -0
- sphinx_java_autodoc/pages.py +140 -0
- sphinx_java_autodoc/render.py +4 -0
- sphinx_java_autodoc-0.3.0.dist-info/METADATA +87 -0
- sphinx_java_autodoc-0.3.0.dist-info/RECORD +15 -0
- sphinx_java_autodoc-0.2.0.dist-info/METADATA +0 -109
- sphinx_java_autodoc-0.2.0.dist-info/RECORD +0 -14
- {sphinx_java_autodoc-0.2.0.dist-info → sphinx_java_autodoc-0.3.0.dist-info}/WHEEL +0 -0
- {sphinx_java_autodoc-0.2.0.dist-info → sphinx_java_autodoc-0.3.0.dist-info}/entry_points.txt +0 -0
- {sphinx_java_autodoc-0.2.0.dist-info → sphinx_java_autodoc-0.3.0.dist-info}/licenses/LICENSE +0 -0
sphinx_java_autodoc/__init__.py
CHANGED
|
@@ -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
|
|
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,
|
|
14
|
+
from .extractor import VERSION, extract
|
|
15
15
|
from .javadoc import check_mapping
|
|
16
|
-
from .model import
|
|
17
|
-
|
|
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
|
-
|
|
160
|
-
|
|
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
|
-
|
|
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
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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
|
-
|
|
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)
|
sphinx_java_autodoc/__main__.py
CHANGED
|
@@ -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
|
-
|
|
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 =
|
|
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
|
sphinx_java_autodoc/domain.py
CHANGED
|
@@ -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
|
-
|
|
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
|
sphinx_java_autodoc/extractor.py
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
71
|
-
|
|
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
|
-
|
|
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
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
132
|
+
@Override
|
|
133
|
+
public String getDescription() {
|
|
134
|
+
return description;
|
|
135
|
+
}
|
|
124
136
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
137
|
+
@Override
|
|
138
|
+
public Kind getKind() {
|
|
139
|
+
return Kind.STANDARD;
|
|
140
|
+
}
|
|
129
141
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
142
|
+
@Override
|
|
143
|
+
public List<String> getNames() {
|
|
144
|
+
return List.of(name);
|
|
145
|
+
}
|
|
134
146
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
147
|
+
@Override
|
|
148
|
+
public String getParameters() {
|
|
149
|
+
return parameters;
|
|
150
|
+
}
|
|
139
151
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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()
|
|
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
|
}
|
sphinx_java_autodoc/model.py
CHANGED
|
@@ -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())
|
sphinx_java_autodoc/render.py
CHANGED
|
@@ -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
|
+
[](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml)
|
|
34
|
+
[](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
|
-
[](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,,
|
|
File without changes
|
{sphinx_java_autodoc-0.2.0.dist-info → sphinx_java_autodoc-0.3.0.dist-info}/entry_points.txt
RENAMED
|
File without changes
|
{sphinx_java_autodoc-0.2.0.dist-info → sphinx_java_autodoc-0.3.0.dist-info}/licenses/LICENSE
RENAMED
|
File without changes
|