This is an automated email from the ASF dual-hosted git repository.
tballison pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tika.git
The following commit(s) were added to refs/heads/main by this push:
new c1ba0f6bfb javadoc fix (#2934)
c1ba0f6bfb is described below
commit c1ba0f6bfbc785aa8f1f15c6a9f59efbe9036046
Author: Tim Allison <[email protected]>
AuthorDate: Tue Jul 7 19:53:15 2026 -0400
javadoc fix (#2934)
---
.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 df37fcfe12..8fda7a6fc1 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>
