This is an automated email from the ASF dual-hosted git repository. tballison pushed a commit to branch 3x-fix-javadocs in repository https://gitbox.apache.org/repos/asf/tika.git
commit 7b4c1f3df4bf838e74e6b3af52ddb4cc7eecd343 Author: tallison <[email protected]> AuthorDate: Wed Jul 15 14:57:07 2026 -0400 backport javadocs aggregate fix from main --- .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>
