From d9490aece5836997d71ded6fd752d1b503347e06 Mon Sep 17 00:00:00 2001 From: David Li Date: Mon, 18 Dec 2023 15:04:57 -0500 Subject: [PATCH] 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 | 21 ++++++ 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, 39 insertions(+), 90 deletions(-) create mode 100644 ci/conda_env_java.txt delete mode 100644 docs/source/java/api/adbc_driver_manager.rst diff --git a/ci/conda_env_java.txt b/ci/conda_env_java.txt new file mode 100644 index 0000000000..2b06fdddd8 --- /dev/null +++ b/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.* diff --git a/ci/scripts/docs_build.sh b/ci/scripts/docs_build.sh index 261786b99a..dcdf27a617 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 a25fb6653b..89394e598f 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/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 ###################################### 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 6c4ec2d10f..0000000000 --- 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 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 klass, Map 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`` 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 e93406f3c4..a316867429 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 78215a0e90..3f31421e41 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 972e55b00b..8e166b59e7 100644 --- a/java/pom.xml +++ b/java/pom.xml @@ -219,17 +219,20 @@ + org.apache.maven.plugins maven-javadoc-plugin - 3.4.1 + 3.6.3 - - -package all,-missing https://arrow.apache.org/docs/java/reference/ + + 8 + public 1.8