This is an automated email from the ASF dual-hosted git repository.
tballison pushed a commit to branch branch_3x
in repository https://gitbox.apache.org/repos/asf/tika.git
The following commit(s) were added to refs/heads/branch_3x by this push:
new 883805d6f2 backport javadocs aggregate fix from main (#2958)
883805d6f2 is described below
commit 883805d6f28777aa5e540cd324e580218a70c202
Author: Tim Allison <[email protected]>
AuthorDate: Wed Jul 15 16:07:30 2026 -0400
backport javadocs aggregate fix from main (#2958)
---
.github/scripts/check_javadoc_sourcepath.py | 97 +++++++++++++++++++++++++++++
tika-parent/pom.xml | 12 +++-
2 files changed, 108 insertions(+), 1 deletion(-)
diff --git a/.github/scripts/check_javadoc_sourcepath.py
b/.github/scripts/check_javadoc_sourcepath.py
new file mode 100644
index 0000000000..da5cfbd4f4
--- /dev/null
+++ b/.github/scripts/check_javadoc_sourcepath.py
@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Guard the hand-maintained <sourcepath> in tika-parent/pom.xml used by the
+TIKA-4318 javadoc:aggregate workaround. That list must name every module's
+src/main/java (except tika-grpc); a module missing from it is silently dropped
+from the aggregated API docs. Run this right before building the javadocs.
+
+ check: python3 .github/scripts/check_javadoc_sourcepath.py [repo_root]
+ fix: python3 .github/scripts/check_javadoc_sourcepath.py --fix [repo_root]
+
+Exit 0 = list matches the reactor; 1 = drift (missing/stale roots) or --fix
rewrote it.
+"""
+import os
+import re
+import sys
+
+PRUNE = {"target", ".git", ".local_m2_repo", "node_modules", ".mvn"}
+EXCLUDE_MODULE_PREFIX = "tika-grpc/" # protobuf gen-sources not on
the aggregate classpath
+POM = "tika-parent/pom.xml"
+
+
+def actual_roots(root: str):
+ roots = set()
+ for dirpath, dirnames, _ in os.walk(root):
+ dirnames[:] = [d for d in dirnames if d not in PRUNE]
+ if not dirpath.replace(os.sep, "/").endswith("/src/main/java"):
+ continue
+ rel = os.path.relpath(dirpath, root).replace(os.sep, "/")
+ if rel.startswith(EXCLUDE_MODULE_PREFIX):
+ continue
+ for _, _, files in os.walk(dirpath):
+ if any(f.endswith(".java") and f != "package-info.java" for f in
files):
+ roots.add(rel)
+ break
+ return roots
+
+
+def listed_roots(pom_text: str):
+ m = re.search(r"<sourcepath>([^<]*)</sourcepath>", pom_text)
+ if not m:
+ sys.exit(f"ERROR: no <sourcepath> found in {POM}")
+ return set(p.strip() for p in m.group(1).split(";") if p.strip()), m
+
+
+def main() -> int:
+ args = [a for a in sys.argv[1:] if a != "--fix"]
+ fix = "--fix" in sys.argv
+ root = os.path.abspath(args[0] if args else ".")
+ pom_path = os.path.join(root, POM)
+ text = open(pom_path, encoding="utf-8").read()
+
+ actual = actual_roots(root)
+ listed, m = listed_roots(text)
+ missing = sorted(actual - listed) # modules present but NOT in the list
-> dropped from docs
+ stale = sorted(listed - actual) # entries in the list that no longer
exist
+
+ if not missing and not stale:
+ print(f"OK: javadoc <sourcepath> covers all {len(actual)} module
source roots.")
+ return 0
+
+ if fix:
+ new_list = ";".join(sorted(actual))
+ open(pom_path, "w", encoding="utf-8").write(
+ text[: m.start(1)] + new_list + text[m.end(1):])
+ print(f"FIXED: rewrote <sourcepath> in {POM} ({len(actual)} roots).")
+ return 0
+
+ print(f"ERROR: javadoc <sourcepath> in {POM} is out of sync with the
reactor.\n")
+ if missing:
+ print(" MISSING (module exists but is not in <sourcepath> -> its API
docs are dropped):")
+ for r in missing:
+ print(f" {r}")
+ if stale:
+ print(" STALE (in <sourcepath> but no longer a module source root):")
+ for r in stale:
+ print(f" {r}")
+ print("\nFix: re-run with --fix, or edit tika-parent/pom.xml's javadoc
<sourcepath>.")
+ print("See TIKA-4318.")
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tika-parent/pom.xml b/tika-parent/pom.xml
index 989bf3e6b3..e83ce2bab2 100644
--- a/tika-parent/pom.xml
+++ b/tika-parent/pom.xml
@@ -1532,7 +1532,17 @@
<version>${maven.javadoc.version}</version>
<configuration>
<doclint>none</doclint>
- <sourcepath>src/main/java</sourcepath>
+ <!-- TIKA-4318: an explicit multi-root sourcepath forces the
javadoc plugin onto its
+ legacy (pre-JPMS) -sourcepath code path, so
javadoc:aggregate actually produces a
+ combined report. Tika modules carry Automatic-Module-Name
manifest hints but have no
+ module-info.java; without this, the plugin runs javadoc in
modular (module source
+ path) mode, classifies the reactor modules inconsistently
as named vs unnamed, and
+ javadoc aborts ('aggregated report for both named and
unnamed modules is not
+ possible'). tika-grpc is excluded: its protobuf
generated-sources and compile deps
+ are not on the aggregate classpath. NOTE: keep this list in
sync when modules are
+ added or removed (see TIKA-4318). -->
+
<sourcepath>tika-app/src/main/java;tika-batch/src/main/java;tika-core/src/main/java;tika-detectors/tika-detector-magika/src/main/java;tika-detectors/tika-detector-siegfried/src/main/java;tika-dotnet/src/main/java;tika-eval/tika-eval-app/src/main/java;tika-eval/tika-eval-core/src/main/java;tika-example/src/main/java;tika-fuzzing/src/main/java;tika-handlers/tika-handler-boilerpipe/src/main/java;tika-java7/src/main/java;tika-langdetect/tika-langdetect-lingo24/src/main/java;tik
[...]
+ <subpackages>org.apache.tika</subpackages>
</configuration>
</plugin>
</plugins>
