This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new d9490aec docs: generate Javadocs (#1362)
d9490aec is described below
commit d9490aece5836997d71ded6fd752d1b503347e06
Author: David Li <[email protected]>
AuthorDate: Mon Dec 18 15:04:57 2023 -0500
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/{scripts/docs_build.sh => conda_env_java.txt} | 33 ++--------
ci/scripts/docs_build.sh | 6 ++
docker-compose.yml | 2 +-
docs/source/java/api/adbc_driver_manager.rst | 79 ------------------------
docs/source/java/api/index.rst | 10 ++-
docs/source/java/driver_manager.rst | 2 +-
java/pom.xml | 9 ++-
7 files changed, 22 insertions(+), 119 deletions(-)
diff --git a/ci/scripts/docs_build.sh b/ci/conda_env_java.txt
old mode 100755
new mode 100644
similarity index 50%
copy from ci/scripts/docs_build.sh
copy to ci/conda_env_java.txt
index 261786b9..2b06fddd
--- a/ci/scripts/docs_build.sh
+++ b/ci/conda_env_java.txt
@@ -1,4 +1,3 @@
-#!/usr/bin/env bash
# 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
@@ -16,31 +15,7 @@
# specific language governing permissions and limitations
# under the License.
-set -ex
-
-main() {
- local -r source_dir="${1}"
-
- pushd "$source_dir/c/apidoc"
- doxygen
- popd
-
- pushd "$source_dir/docs"
- make html
- make doctest
- popd
-
- for desc_file in $(find "${source_dir}/r" -name DESCRIPTION); do
- local pkg=$(dirname "$desc_file")
- local pkg_name=$(basename $pkg)
- # Only build R documentation for installed packages (e.g., so that
- # Python's documentation build can run without installing the R
- # packages). Packages are installed in ci/scripts/r_build.sh
- if Rscript -e "loadNamespace('$pkg_name')" ; then
- R -e "pkgdown::build_site_github_pages(pkg = '$pkg', dest_dir =
'$source_dir/docs/build/html/r/$pkg_name')"
- fi
- done
-
-}
-
-main "$@"
+maven
+# maven javadocs build appears to fail under Java 21
+# maven javadocs build appears to emit the wrong stylesheet under Java 8
+openjdk=17.*
diff --git a/ci/scripts/docs_build.sh b/ci/scripts/docs_build.sh
index 261786b9..dcdf27a6 100755
--- a/ci/scripts/docs_build.sh
+++ b/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)
diff --git a/docker-compose.yml b/docker-compose.yml
index a25fb665..89394e59 100644
--- a/docker-compose.yml
+++ b/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/bui [...]
+ /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/scri [...]
############################ Java JARs ######################################
diff --git a/docs/source/java/api/adbc_driver_manager.rst
b/docs/source/java/api/adbc_driver_manager.rst
deleted file mode 100644
index 6c4ec2d1..00000000
--- a/docs/source/java/api/adbc_driver_manager.rst
+++ /dev/null
@@ -1,79 +0,0 @@
-.. 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.
-
-============================
-``Java ADBC Driver Manager``
-============================
-
-Java ADBC Wrapper for JDBC
-==========================
-
-The Java ADBC Driver Manager provides a means to manage ADBC drivers and
facilitate connections to databases using the ADBC API. This particular
implementation wraps around the JDBC API.
-
-Constants
----------
-
-.. data:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.PARAM_DATASOURCE
-
- A parameter for creating an ``AdbcDatabase`` from a ``DataSource``.
-
-.. data:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.PARAM_JDBC_QUIRKS
-
- A parameter for specifying backend-specific configuration.
-
-.. data:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.PARAM_URI
-
- A parameter for specifying a URI to connect to, aligning with the C/Go
implementations.
-
-Classes
--------
-
-.. class:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver
-
- An ADBC driver implementation that wraps around the JDBC API.
-
- .. method:: open(Map<String, Object> parameters)
-
- Opens a new database connection using the specified parameters.
-
-.. class:: org.apache.arrow.adbc.driver.jdbc.JdbcDataSourceDatabase
-
- Represents an ADBC database backed by a JDBC ``DataSource``.
-
-Utilities
----------
-
-The ``JdbcDriver`` class provides utility methods to fetch and validate
parameters from the provided options map.
-
-.. method:: org.apache.arrow.adbc.driver.jdbc.JdbcDriver.getParam(Class<T>
klass, Map<String, Object> parameters, String... choices)
-
- Retrieves a parameter from the provided map, validating its type and
ensuring no duplicates.
-
-Usage
-=====
-
-The ``JdbcDriver`` class is registered with the ``AdbcDriverManager`` upon
class loading. To utilize this driver:
-
-1. Ensure the necessary dependencies are in place.
-2. Create a ``Map<String, Object>`` containing the connection parameters.
-3. Use the ``AdbcDriverManager`` to obtain an instance of the ``JdbcDriver``.
-4. Open a new database connection using the driver's ``open`` method.
-
-Exceptions
-==========
-
-Any errors during the driver operations throw the ``AdbcException``. This
exception provides detailed messages indicating the nature of the problem.
diff --git a/docs/source/java/api/index.rst b/docs/source/java/api/index.rst
index e93406f3..a3168674 100644
--- a/docs/source/java/api/index.rst
+++ b/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.
diff --git a/docs/source/java/driver_manager.rst
b/docs/source/java/driver_manager.rst
index 78215a0e..3f31421e 100644
--- a/docs/source/java/driver_manager.rst
+++ b/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>`_.
diff --git a/java/pom.xml b/java/pom.xml
index 972e55b0..8e166b59 100644
--- a/java/pom.xml
+++ b/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>
