This is an automated email from the ASF dual-hosted git repository. tballison pushed a commit to branch TIKA-4318-javadoc-fix in repository https://gitbox.apache.org/repos/asf/tika.git
commit 26c8f916586de94e44c3bd0be387a1190f6155b2 Author: tallison <[email protected]> AuthorDate: Tue Jul 7 11:44:21 2026 -0400 javadoc fix --- .github/scripts/check_javadoc_sourcepath.py | 97 ++++++++++++++++++++++ .../pages/maintainers/release-guides/tika.adoc | 3 + docs/modules/ROOT/pages/maintainers/site.adoc | 54 ++++++++++++ tika-parent/pom.xml | 12 ++- 4 files changed, 165 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/docs/modules/ROOT/pages/maintainers/release-guides/tika.adoc b/docs/modules/ROOT/pages/maintainers/release-guides/tika.adoc index 428bb3a458..e614cb7940 100644 --- a/docs/modules/ROOT/pages/maintainers/release-guides/tika.adoc +++ b/docs/modules/ROOT/pages/maintainers/release-guides/tika.adoc @@ -416,6 +416,9 @@ Refresh the website documentation to reflect the new release: * Update download links * Update version numbers in documentation * Add release notes +* Publish the aggregated API docs (Javadoc) -- see + xref:maintainers/site.adoc[Publishing the Documentation Site], "Publishing the + API docs (Javadoc)" === Release Docker and Helm Images diff --git a/docs/modules/ROOT/pages/maintainers/site.adoc b/docs/modules/ROOT/pages/maintainers/site.adoc index ce751cf4a1..6d3f1b5474 100644 --- a/docs/modules/ROOT/pages/maintainers/site.adoc +++ b/docs/modules/ROOT/pages/maintainers/site.adoc @@ -183,6 +183,60 @@ cd /path/to/tika-site svn commit -m "Update 4.0.0 docs" ---- +== Publishing the API docs (Javadoc) + +The per-version API docs at `https://tika.apache.org/<version>/api/` are a single +aggregated Javadoc across all modules, generated from the release source tree and +copied into the tika-site checkout next to the Antora docs. + +[NOTE] +==== +Tika modules declare an `Automatic-Module-Name` but ship no `module-info.java`, so +`maven-javadoc-plugin`'s aggregate goal defaults to a modular invocation that emits +nothing (see https://issues.apache.org/jira/browse/TIKA-4318[TIKA-4318]). +`tika-parent` works around this with an explicit `<sourcepath>` listing every +module's `src/main/java` (except `tika-grpc`). That list is hand-maintained, so run +the check in step 2 before generating -- a newly added module would otherwise drop +out of the docs silently. +==== + +. Build and install first. `javadoc:aggregate` compiles nothing; it needs every + module jar (and grpc's generated sources) in the local repo. `-Pfast` skips tests + for speed: ++ +[source,bash] +---- +mvn clean install -Pfast +---- + +. Verify the aggregate `<sourcepath>` still covers every module: ++ +[source,bash] +---- +python3 .github/scripts/check_javadoc_sourcepath.py +# on failure it names the missing module(s); regenerate the list with --fix: +python3 .github/scripts/check_javadoc_sourcepath.py --fix +---- + +. Generate the aggregate Javadoc (output in `target/reports/apidocs/`; `tika-grpc` + is intentionally excluded): ++ +[source,bash] +---- +mvn javadoc:aggregate +---- + +. Copy it into the tika-site checkout as this version's `api/` directory and commit: ++ +[source,bash] +---- +mkdir -p /path/to/tika-site/publish/<version> +cp -r target/reports/apidocs /path/to/tika-site/publish/<version>/api +cd /path/to/tika-site +svn add publish/<version> +svn commit -m "Add <version> API docs" +---- + == Site Structure The Antora configuration files: diff --git a/tika-parent/pom.xml b/tika-parent/pom.xml index 248057a48f..bd13daa43f 100644 --- a/tika-parent/pom.xml +++ b/tika-parent/pom.xml @@ -1716,7 +1716,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-annotation-processor/src/main/java;tika-app/src/main/java;tika-bundles/tika-bundle-standard/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-encoding-detectors/tika-encoding-detector-html/src/main/java;tika-encoding-detectors/tika-encoding-detector-icu4j/src/main/java;tika-encoding-detectors/tika-encoding-detector-mojibuster/src/main/java;tika-encoding-detectors [...] + <subpackages>org.apache.tika</subpackages> </configuration> </plugin> </plugins>
