This is an automated email from the ASF dual-hosted git repository.
indhub 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 ea6ee0d Add Java API docs generation (#13071)
ea6ee0d is described below
commit ea6ee0d217dcdac29fe0a22bdce019168a76a060
Author: Aaron Markham <[email protected]>
AuthorDate: Tue Nov 13 12:17:44 2018 -0800
Add Java API docs generation (#13071)
* add Java API docs generation; split out from Scala API docs
* bumping file for ci
* make scala docs build compatible for 2.11.x and 2.12.x scala
fix typo
* fix exit bug
---
docs/mxdoc.py | 31 ++++++++++++++++++++++++-------
docs/settings.ini | 11 +++++++++++
2 files changed, 35 insertions(+), 7 deletions(-)
diff --git a/docs/mxdoc.py b/docs/mxdoc.py
index 7092b9e..8570cae 100644
--- a/docs/mxdoc.py
+++ b/docs/mxdoc.py
@@ -40,11 +40,12 @@ if _DOC_SET not in parser.sections():
for section in [ _DOC_SET ]:
print("Document sets to generate:")
- for candidate in [ 'scala_docs', 'clojure_docs', 'doxygen_docs', 'r_docs'
]:
+ for candidate in [ 'scala_docs', 'java_docs', 'clojure_docs',
'doxygen_docs', 'r_docs' ]:
print('%-12s : %s' % (candidate, parser.get(section, candidate)))
_MXNET_DOCS_BUILD_MXNET = parser.getboolean('mxnet', 'build_mxnet')
_SCALA_DOCS = parser.getboolean(_DOC_SET, 'scala_docs')
+_JAVA_DOCS = parser.getboolean(_DOC_SET, 'java_docs')
_CLOJURE_DOCS = parser.getboolean(_DOC_SET, 'clojure_docs')
_DOXYGEN_DOCS = parser.getboolean(_DOC_SET, 'doxygen_docs')
_R_DOCS = parser.getboolean(_DOC_SET, 'r_docs')
@@ -58,7 +59,8 @@ _CODE_MARK = re.compile('^([ ]*)```([\w]*)')
# language names and the according file extensions and comment symbol
_LANGS = {'python' : ('py', '#'),
'r' : ('R','#'),
- 'scala' : ('scala', '#'),
+ 'scala' : ('scala', '//'),
+ 'java' : ('java', '//'),
'julia' : ('jl', '#'),
'perl' : ('pl', '#'),
'cpp' : ('cc', '//'),
@@ -101,7 +103,7 @@ def build_r_docs(app):
_run_cmd('mkdir -p ' + dest_path + '; mv ' + pdf_path + ' ' + dest_path)
def build_scala(app):
- """build scala for scala docs and clojure docs to use"""
+ """build scala for scala docs, java docs, and clojure docs to use"""
_run_cmd("cd %s/.. && make scalapkg" % app.builder.srcdir)
_run_cmd("cd %s/.. && make scalainstall" % app.builder.srcdir)
@@ -109,13 +111,26 @@ def build_scala_docs(app):
"""build scala doc and then move the outdir"""
scala_path = app.builder.srcdir + '/../scala-package'
# scaldoc fails on some apis, so exit 0 to pass the check
- _run_cmd('cd ' + scala_path + '; scaladoc `find . -type f -name "*.scala"
| egrep \"\/core|\/infer\" | egrep -v \"Suite\"`; exit 0')
+ _run_cmd('cd ' + scala_path + '; scaladoc `find . -type f -name "*.scala"
| egrep \"\/core|\/infer\" | egrep -v \"Suite|javaapi\"`; exit 0')
dest_path = app.builder.outdir + '/api/scala/docs'
_run_cmd('rm -rf ' + dest_path)
_run_cmd('mkdir -p ' + dest_path)
+ # 'index' and 'package.html' do not exist in later versions of scala;
delete these after upgrading scala>2.12.x
scaladocs = ['index', 'index.html', 'org', 'lib', 'index.js',
'package.html']
for doc_file in scaladocs:
- _run_cmd('cd ' + scala_path + ' && mv -f ' + doc_file + ' ' +
dest_path)
+ _run_cmd('cd ' + scala_path + ' && mv -f ' + doc_file + ' ' +
dest_path + '; exit 0')
+
+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/'
+ # 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')
+ dest_path = app.builder.outdir + '/api/java/docs'
+ _run_cmd('rm -rf ' + dest_path)
+ _run_cmd('mkdir -p ' + dest_path)
+ javadocs = ['index', 'index.html', 'org', 'lib', 'index.js',
'package.html']
+ for doc_file in javadocs:
+ _run_cmd('cd ' + java_path + ' && mv -f ' + doc_file + ' ' + dest_path
+ '; exit 0')
def build_clojure_docs(app):
"""build clojure doc and then move the outdir"""
@@ -125,7 +140,7 @@ def build_clojure_docs(app):
_run_cmd('rm -rf ' + dest_path)
_run_cmd('mkdir -p ' + dest_path)
clojure_doc_path = app.builder.srcdir +
'/../contrib/clojure-package/target/doc'
- _run_cmd('cd ' + clojure_doc_path + ' && cp -r * ' + dest_path)
+ _run_cmd('cd ' + clojure_doc_path + ' && cp -r * ' + dest_path + '; exit
0')
def _convert_md_table_to_rst(table):
"""Convert a markdown table to rst format"""
@@ -404,7 +419,6 @@ def add_buttons(app, docname, source):
# source[i] = '\n'.join(lines)
def setup(app):
-
# If MXNET_DOCS_BUILD_MXNET is set something different than 1
# Skip the build step
if os.getenv('MXNET_DOCS_BUILD_MXNET', '1') == '1' or
_MXNET_DOCS_BUILD_MXNET:
@@ -419,6 +433,9 @@ def setup(app):
if _SCALA_DOCS:
print("Building Scala Docs!")
app.connect("builder-inited", build_scala_docs)
+ if _JAVA_DOCS:
+ print("Building Java Docs!")
+ app.connect("builder-inited", build_java_docs)
if _CLOJURE_DOCS:
print("Building Clojure Docs!")
app.connect("builder-inited", build_clojure_docs)
diff --git a/docs/settings.ini b/docs/settings.ini
index da2e641..1f20971 100644
--- a/docs/settings.ini
+++ b/docs/settings.ini
@@ -10,65 +10,76 @@ scala_docs = 0
[document_sets_default]
clojure_docs = 1
doxygen_docs = 1
+java_docs = 1
r_docs = 0
scala_docs = 1
[document_sets_1.2.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 1
[document_sets_v1.2.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 1
[document_sets_1.1.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_v1.1.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_1.0.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_v1.0.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_0.12.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_v0.12.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_0.11.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
[document_sets_v0.11.0]
clojure_docs = 0
doxygen_docs = 1
+java_docs = 0
r_docs = 0
scala_docs = 0
