Skip to content

Latest commit

 

History

History
122 lines (87 loc) · 3.71 KB

CONTRIBUTING.rst

File metadata and controls

122 lines (87 loc) · 3.71 KB
Raw

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.

Java

The Java cookbooks require:

  • Java JDK (11+)
  • Maven

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.

If the environment variable ARROW_NIGHTLY is defined and not 0 the cookbooks will be run against the latest development version of Arrow published by the Nightly jobs.

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

When run, Java code snippets are wrapped in a simple main class

// Any imports get put here

public class Example {
    public static void main (String[] args) {
        // Your code gets inserted here
    }
}

If your code is more complicated, you can explicitly define public class Example, the above wrapping won't happen and the code will be run as-is.

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)

> cd java/ext
> black javadoctest.py

Sort imports (before committing)

> cd java/ext
> isort javadoctest.py

Lint code (before committing)

> cd java/ext
> flake8

All participation in the Apache Arrow project is governed by the Apache Software Foundation’s code of conduct.