You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mxnet.apache.org by la...@apache.org on 2018/11/25 18:11:52 UTC
[incubator-mxnet] branch master updated: Initial website
documentation for Java API (#13289)
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 <an...@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)