This is an automated email from the ASF dual-hosted git repository. lanking pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-mxnet.git
The following commit(s) were added to refs/heads/master by this push: new d412f4f Initial website documentation for Java API (#13289) d412f4f is described below commit d412f4faee862c0bccf608b9be440a5a4bccc3fe Author: Andrew Ayres <andrew.f.ay...@gmail.com> AuthorDate: Sun Nov 25 10:11:36 2018 -0800 Initial website documentation for Java API (#13289) * Initial website documentation for Java API * Changing paths to be relative * Refactoring Java API website landing page * Update Java web docs based on feedback * Minor formatting fixes * Update maven repo to nightly build so that java will be available prior to 1.4.0 release * Adding java tutorial index to test_sanity_tutorials whitelist * Fix link to javadocs * Fix javadoc for infer package and minor install doc fix * Minor path fix --- docs/_static/js/sidebar.js | 2 +- docs/_static/mxnet-theme/navbar.html | 2 + docs/api/java/index.md | 15 ++++ docs/install/build_from_source.md | 3 +- docs/install/java_setup.md | 114 +++++++++++++++++++++++++++++++ docs/mxdoc.py | 5 +- docs/tutorials/java/index.md | 8 +++ tests/tutorials/test_sanity_tutorials.py | 1 + 8 files changed, 146 insertions(+), 4 deletions(-) diff --git a/docs/_static/js/sidebar.js b/docs/_static/js/sidebar.js index 3e7ad41..c5b8b51 100644 --- a/docs/_static/js/sidebar.js +++ b/docs/_static/js/sidebar.js @@ -1,5 +1,5 @@ /*Preprocess*/ -var LANG = ['python', 'c++', 'clojure', 'julia', 'perl', 'r', 'scala']; +var LANG = ['python', 'c++', 'clojure', 'julia', 'perl', 'r', 'scala', 'java']; var TITLE_WITH_LANG = ['/get_started/', '/tutorials/', '/faq/', '/architecture/', '/community/']; for(var i = 0; i < LANG.length; ++i) { TITLE_WITH_LANG.push('/api/' + LANG[i] + '/'); diff --git a/docs/_static/mxnet-theme/navbar.html b/docs/_static/mxnet-theme/navbar.html index 977d005..50c3deb 100644 --- a/docs/_static/mxnet-theme/navbar.html +++ b/docs/_static/mxnet-theme/navbar.html @@ -27,6 +27,7 @@ <li><a class="main-nav-link" href="{{url_root}}api/perl/index.html">Perl</a></li> <li><a class="main-nav-link" href="{{url_root}}api/r/index.html">R</a></li> <li><a class="main-nav-link" href="{{url_root}}api/scala/index.html">Scala</a></li> + <li><a class="main-nav-link" href="{{url_root}}api/java/index.html">Java</a></li> </ul> </span> @@ -80,6 +81,7 @@ <li><a class="main-nav-link" href="{{url_root}}api/perl/index.html">Perl</a></li> <li><a class="main-nav-link" href="{{url_root}}api/r/index.html">R</a></li> <li><a class="main-nav-link" href="{{url_root}}api/scala/index.html">Scala</a></li> + <li><a class="main-nav-link" href="{{url_root}}api/java/index.html">Java</a></li> </ul> </li> <li class="dropdown-submenu"> diff --git a/docs/api/java/index.md b/docs/api/java/index.md new file mode 100644 index 0000000..b2ae035 --- /dev/null +++ b/docs/api/java/index.md @@ -0,0 +1,15 @@ +# MXNet - Java Inference API + +MXNet supports Java for performing inference on a trained model. The MXNet Java Inference API is an extension of the [Scala Infer API](../../api/scala/infer.html) which provides model loading and inference functionality. + +The goal of the MXNet Java package is to provide an efficient and easy to use inference API. +The MXNet Java package makes it easy to quickly deploy an existing model into a production level Java ecosystem. + +## Installation +* [MXNet Java Inference API setup instructions](../../install/java_setup.md) + +## Tutorials +See the [tutorial page](../../tutorials/index.html#java-tutorials) for detailed tutorials and examples using the Java Inference API. + +## Java Inference API Reference +The [Java Infer API javadocs](docs/index.html#org.apache.mxnet.infer.package) provides detailed API information. \ No newline at end of file diff --git a/docs/install/build_from_source.md b/docs/install/build_from_source.md index b28fca3..e41b1d0 100644 --- a/docs/install/build_from_source.md +++ b/docs/install/build_from_source.md @@ -32,9 +32,9 @@ MXNet's newest and most popular API is Gluon. Gluon is built into the Python bin - [Perl](../api/perl/index.html) - [R](../api/r/index.html) - [Scala](../api/scala/index.html) + - [Java](../api/java/index.html) <hr> - ## Build Instructions by Operating System Detailed instructions are provided per operating system. Each of these guides also covers how to install the specific [Language Bindings](#installing-mxnet-language-bindings) you require. @@ -284,3 +284,4 @@ The following table provides links to each language binding by operating system: | Perl | [Ubuntu guide](ubuntu_setup.html#install-the-mxnet-package-for-perl) | [OSX guide](osx_setup.html#install-the-mxnet-package-for-perl) | n/a | | R | [Ubuntu guide](ubuntu_setup.html#install-the-mxnet-package-for-r) | [OSX guide](osx_setup.html#install-the-mxnet-package-for-r) | [Windows guide](windows_setup.html#install-the-mxnet-package-for-r) | | Scala | [Scala guide](scala_setup.html) | [Scala guide](scala_setup.html) | n/a | +| Java | [Java guide](java_setup.html) | [Java Guide](java_setup.html) | n/a | diff --git a/docs/install/java_setup.md b/docs/install/java_setup.md new file mode 100644 index 0000000..5e1ddc9 --- /dev/null +++ b/docs/install/java_setup.md @@ -0,0 +1,114 @@ +# Setup the MXNet Package for Java + +The following instructions are provided for macOS and Ubuntu. Windows is not yet available. + +**Note:** If you use IntelliJ or a similar IDE, you may want to follow the [MXNet-Java on IntelliJ tutorial](../tutorials/java/mxnet_java_on_intellij.html) instead of these instructions. + +<hr> + +## Maven + +### Setup Instructions + +**Step 1.** Install dependencies: + +**macOS Steps** + +```bash +brew update +brew tap caskroom/versions +brew cask install java8 +brew install opencv +brew install maven +``` + +**Ubuntu Steps** + +These scripts will install Maven and its dependencies. You will be running the Scala scripts because the MXNet-Java project has a dependency on the MXNet-Scala project. + +```bash +wget https://raw.githubusercontent.com/apache/incubator-mxnet/master/ci/docker/install/ubuntu_core.sh +wget https://raw.githubusercontent.com/apache/incubator-mxnet/master/ci/docker/install/ubuntu_scala.sh +chmod +x ubuntu_core.sh +chmod +x ubuntu_scala.sh +sudo ./ubuntu_core.sh +sudo ./ubuntu_scala.sh +``` + +**Step 2.** Run the demo MXNet-Java project. + +Go to the [MXNet-Java demo project's README](https://github.com/apache/incubator-mxnet/tree/master/scala-package/mxnet-demo/java-demo) and follow the directions to test the MXNet-Java package installation. + +#### Maven Repository + +Package information can be found in this [Maven Repository](https://repository.apache.org/#nexus-search;gav~org.apache.mxnet~~1.3.1-SNAPSHOT~~) + +**Linux CPU** +```html +<!-- https://mvnrepository.com/artifact/org.apache.mxnet/mxnet-full_2.11-linux-x86_64-cpu --> +<dependency> + <groupId>org.apache.mxnet</groupId> + <artifactId>mxnet-full_2.11-linux-x86_64-cpu</artifactId> + <scope>system</scope> + <systemPath>/system/path/to/jar/mxnet-full_2.11-linux-x86_64-cpu-1.3.1-SNAPSHOT.jar</systemPath> +</dependency> +``` + +**Linux GPU** +```html +<!-- https://mvnrepository.com/artifact/org.apache.mxnet/mxnet-full_2.11-linux-x86_64-gpu --> +<dependency> + <groupId>org.apache.mxnet</groupId> + <artifactId>mxnet-full_2.11-linux-x86_64-gpu</artifactId> + <scope>system</scope> + <systemPath>/system/path/to/jar/mxnet-full_2.11-linux-x86_64-gpu-1.3.1-SNAPSHOT.jar</systemPath> +</dependency> +``` + +**macOS CPU** +```html +<!-- https://mvnrepository.com/artifact/org.apache.mxnet/mxnet-full_2.11-osx-x86_64-cpu --> +<dependency> + <groupId>org.apache.mxnet</groupId> + <artifactId>mxnet-full_2.11-osx-x86_64-cpu</artifactId> + <scope>system</scope> + <systemPath>/system/path/to/jar/mxnet-full_2.11-osx-x86_64-cpu-1.3.1-SNAPSHOT.jar</systemPath> +</dependency> +``` + +<hr> + +## Source + +The previously mentioned setup with Maven is recommended. Otherwise, the following instructions for macOS and Ubuntu are provided for reference only: + +| OS | Step 1 | Step 2 | +|---|---|---| +|macOS | [Shared Library for macOS](../install/osx_setup.html#build-the-shared-library) | [Scala Package for macOS](http://mxnet.incubator.apache.org/install/osx_setup.html#install-the-mxnet-package-for-scala) | +| Ubuntu | [Shared Library for Ubuntu](../install/ubuntu_setup.html#installing-mxnet-on-ubuntu) | [Scala Package for Ubuntu](http://mxnet.incubator.apache.org/install/ubuntu_setup.html#install-the-mxnet-package-for-scala) | +| Windows | [Shared Library for Windows](../install/windows_setup.html#build-the-shared-library) | <a class="github-button" href="https://github.com/apache/incubator-mxnet/issues/10549" data-size="large" data-show-count="true" aria-label="Issue apache/incubator-mxnet on GitHub">Call for Contribution</a> | + + +#### Build Java from an Existing MXNet Installation +If you have already built MXNet **from source** and are looking to setup Java from that point, you may simply run the following from the MXNet source root: + +``` +make scalapkg +make scalainstall +``` +This will install both the Java Inference API and the required MXNet-Scala package. +<hr> + +## Documentation + +Javadocs are generated as part of the docs build pipeline. You can find them published in the [Java API](../api/java/index.html) section of the website or by going to the [scaladocs output](https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.package) directly. + +To build the docs yourself, follow the [developer build docs instructions](https://github.com/apache/incubator-mxnet/tree/master/docs/build_version_doc#developer-instructions). + +<hr> + +## Resources + +* [Java API](../api/java/index.html) +* [javadocs](../api/java/docs/index.html#org.apache.mxnet.package) +* [MXNet-Java Tutorials](../../tutorials/index.html#java-tutorials) diff --git a/docs/mxdoc.py b/docs/mxdoc.py index 5e86c1c..136d761 100644 --- a/docs/mxdoc.py +++ b/docs/mxdoc.py @@ -127,9 +127,10 @@ def build_scala_docs(app): def build_java_docs(app): """build java docs and then move the outdir""" - java_path = app.builder.srcdir + '/../scala-package/core/src/main/scala/org/apache/mxnet/' + java_path = app.builder.srcdir + '/../scala-package' # scaldoc fails on some apis, so exit 0 to pass the check - _run_cmd('cd ' + java_path + '; scaladoc `find . -type f -name "*.scala" | egrep \"\/javaapi\" | egrep -v \"Suite\"`; exit 0') + find_cmd = '`find . -type f -name "*.scala" | egrep \"\.\/core|\.\/infer\" | egrep \"\/javaapi\" | egrep -v \"Suite\"`' + _run_cmd('cd ' + java_path + '; scaladoc ' + find_cmd +'; exit 0') dest_path = app.builder.outdir + '/api/java/docs' _run_cmd('rm -rf ' + dest_path) _run_cmd('mkdir -p ' + dest_path) diff --git a/docs/tutorials/java/index.md b/docs/tutorials/java/index.md new file mode 100644 index 0000000..87d7289 --- /dev/null +++ b/docs/tutorials/java/index.md @@ -0,0 +1,8 @@ +# Tutorials + +```eval_rst +.. toctree:: + :glob: + + * +``` diff --git a/tests/tutorials/test_sanity_tutorials.py b/tests/tutorials/test_sanity_tutorials.py index 9e5c38a..644a611 100644 --- a/tests/tutorials/test_sanity_tutorials.py +++ b/tests/tutorials/test_sanity_tutorials.py @@ -57,6 +57,7 @@ whitelist = ['basic/index.md', 'vision/index.md', 'tensorrt/index.md', 'tensorrt/inference_with_trt.md', + 'java/index.md', 'java/mxnet_java_on_intellij.md', 'java/ssd_inference.md'] whitelist_set = set(whitelist)