| .. 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. |
| |
| Building the Java Cookbook |
| ========================= |
| The Java cookbook uses the Sphinx documentation system. |
| |
| Dependencies |
| ------------------------- |
| The following are required to successfully build the Java cookbook: |
| |
| Python |
| ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| The cookbook build tooling depends upon Python, and the ability to |
| install needed packages via pip, to build the Java cookbook. The |
| dependency packages managed via pip by build scripts are found at |
| `requirements.txt <requirements.txt>`_. |
| |
| Java Shell |
| ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| For Java cookbook we are running these with Java Shell tool - |
| `JShell <https://docs.oracle.com/en/java/javase/11/jshell/introduction-jshell.html>`_ |
| |
| .. code-block:: bash |
| |
| > java --version |
| java 11.0.14 2022-01-18 LTS |
| Java(TM) SE Runtime Environment 18.9 (build 11.0.14+8-LTS-263) |
| |
| .. code-block:: bash |
| |
| > jshell --version |
| jshell 11.0.14 |
| |
| |
| Build Process |
| ------------------------- |
| Run ``make java`` from the cookbook root directory (the one where |
| the ``README.rst`` exists) to install all necessary dependencies |
| and compile the cookbook to HTML. |
| |
| You will see the compiled result inside the ``build/java`` directory. |
| |
| Testing Java Recipes |
| ==================== |
| |
| All recipes in the cookbook must be tested. The cookbook uses |
| ``javadoctest`` to verify the recipes. |
| |
| Run ``make javatest`` from the cookbook root directory |
| to verify that the code for all the recipes runs correctly |
| and provides the expected output. |
| |
| Adding Java Recipes |
| =================== |
| |
| The recipes are written in **reStructuredText** format using |
| the `Sphinx <https://www.sphinx-doc.org/>`_ documentation system. |
| |
| New recipes can be added to one of the existing ``.rst`` files if |
| they suit that section or you can create new sections by adding |
| additional ``.rst`` files in the ``source`` directory. You just |
| need to remember to add them to the ``index.rst`` file in the |
| ``toctree`` for them to become visible. |
| |
| Java Sphinx Directive |
| ===================== |
| |
| To support testing java code documentation a sphinx directive |
| was created: ext/javadoctest.py |
| |
| Execute validations before commit sphinx directive extension: |
| |
| Format code (before committing) |
| |
| .. code-block:: bash |
| |
| > cd java/ext |
| > black javadoctest.py |
| |
| Sort imports (before committing) |
| |
| .. code-block:: bash |
| |
| > cd java/ext |
| > isort javadoctest.py |
| |
| Lint code (before committing) |
| |
| .. code-block:: bash |
| |
| > cd java/ext |
| > flake8 |
| ------------------------------------------------------------------------ |
| |
| All participation in the Apache Arrow project is governed by the Apache |
| Software Foundation’s |
| `code of conduct <https://www.apache.org/foundation/policies/conduct.html>`_. |