docs: generate Javadocs (#1362)

In #1357 I'd like to explore hacking Javadocs into Intersphinx for
better cross-linking, but first we have to actually generate the
Javadocs.

Fixes #1361.

ci/conda_env_java.txt

@@ -0,0 +1,21 @@
+# 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.
+
+maven
+# maven javadocs build appears to fail under Java 21
+# maven javadocs build appears to emit the wrong stylesheet under Java 8
+openjdk=17.*

ci/scripts/docs_build.sh

@@ -30,6 +30,12 @@ main() {
     make doctest
     popd
 
+    pushd "$source_dir/java"
+    mvn site
+    rm -rf "$source_dir/docs/build/java/api"
+    cp -r target/site/apidocs "$source_dir/docs/build/java/api"
+    popd
+
     for desc_file in $(find "${source_dir}/r" -name DESCRIPTION); do
       local pkg=$(dirname "$desc_file")
       local pkg_name=$(basename $pkg)

docker-compose.yml

@@ -28,7 +28,7 @@ services:
     volumes:
       - .:/adbc:delegated
     command: |
-      /bin/bash -c 'git config --global --add safe.directory /adbc && source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge go --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && env ADBC_USE_ASAN=0 ADBC_USE_UBSAN=0 /adbc/ci/scripts/cpp_build.sh /adbc /adbc/build && env CGO_ENABLED=1 /adbc/ci/scripts/go_build.sh /adbc /adbc/build && /adbc/ci/scripts/python_build.sh /adbc /adbc/build && /adbc/ci/scripts/r_build.sh /adbc && /adbc/ci/scripts/docs_build.sh /adbc'
+      /bin/bash -c 'git config --global --add safe.directory /adbc && source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge go --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_java.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && env ADBC_USE_ASAN=0 ADBC_USE_UBSAN=0 /adbc/ci/scripts/cpp_build.sh /adbc /adbc/build && env CGO_ENABLED=1 /adbc/ci/scripts/go_build.sh /adbc /adbc/build && /adbc/ci/scripts/python_build.sh /adbc /adbc/build && /adbc/ci/scripts/r_build.sh /adbc && /adbc/ci/scripts/docs_build.sh /adbc'
 
   ############################ Java JARs ######################################
 

docs/source/java/api/index.rst

@@ -15,11 +15,9 @@
 .. specific language governing permissions and limitations
 .. under the License.
 
-====================
+==================
 Java API Reference
-====================
+==================
 
-.. toctree::
-   :maxdepth: 1
-
-   adbc_driver_manager
+This is a stub page for the Javadocs. If you're seeing this page, it means
+that the actual Javadocs were not generated.

docs/source/java/driver_manager.rst

@@ -35,4 +35,4 @@ To include the ADBC Driver Manager in your Maven project, add the following depe
 API Reference
 =============
 
-See the API reference: :doc:`./api/adbc_driver_manager`.
+See the `API reference <./api/org/apache/arrow/adbc/drivermanager/package-summary.html>`_.

java/pom.xml

@@ -219,17 +219,20 @@
   <reporting>
     <plugins>
       <plugin>
+        <!-- Will only work with JDK 17 (JDK 21 is broken and JDK 8 emits the
+             wrong stylesheet) -->
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
-        <version>3.4.1</version>
+        <version>3.6.3</version>
         <configuration>
-          <!-- Stop it from trying to document the tests -->
-          <additionalOptions>-package</additionalOptions>
           <!-- Ignore missing @return, @throws -->
           <doclint>all,-missing</doclint>
           <links>
             <link>https://arrow.apache.org/docs/java/reference/</link>
           </links>
+	  <!-- Stop it from trying to document the tests -->
+          <release>8</release>
+	  <show>public</show>
           <source>1.8</source>
         </configuration>
         <reportSets>