java/CONTRIBUTING.rst

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>`_.