From 76c59f4acb9fa79857a96a25e8cd0698708bd53c Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Wed, 31 Oct 2018 17:28:43 -0700 Subject: [PATCH 1/4] add Java API docs generation; split out from Scala API docs --- docs/mxdoc.py | 22 +++++++++++++++++++--- docs/settings.ini | 11 +++++++++++ 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/mxdoc.py b/docs/mxdoc.py index 7092b9ee9eaa..3e0d9b2a2c8b 100644 --- a/docs/mxdoc.py +++ b/docs/mxdoc.py @@ -40,11 +40,12 @@ 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') @@ -109,14 +110,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) - scaladocs = ['index', 'index.html', 'org', 'lib', 'index.js', 'package.html'] + scaladocs = ['index.html', 'org', 'lib', 'index.js'] for doc_file in scaladocs: _run_cmd('cd ' + scala_path + ' && mv -f ' + doc_file + ' ' + dest_path) +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.html', 'org', 'lib', 'index.js'] + for doc_file in javadocs: + _run_cmd('cd ' + java_path + ' && mv -f ' + doc_file + ' ' + dest_path) + def build_clojure_docs(app): """build clojure doc and then move the outdir""" clojure_path = app.builder.srcdir + '/../contrib/clojure-package' @@ -419,6 +432,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 b8e486e58e87..86a9d6ac3ec2 100644 --- a/docs/settings.ini +++ b/docs/settings.ini @@ -4,65 +4,76 @@ build_mxnet = 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 From abdc2e3a87747daa83d7e9470a2545425563f797 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Thu, 1 Nov 2018 16:56:51 -0700 Subject: [PATCH 2/4] bumping file for ci --- docs/mxdoc.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/mxdoc.py b/docs/mxdoc.py index 3e0d9b2a2c8b..a0ec39922f9e 100644 --- a/docs/mxdoc.py +++ b/docs/mxdoc.py @@ -417,7 +417,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: From 4c4c6d781994413fd049c115cf0bb881227eed3a Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Mon, 5 Nov 2018 16:11:16 -0800 Subject: [PATCH 3/4] make scala docs build compatible for 2.11.x and 2.12.x scala fix typo --- docs/mxdoc.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/mxdoc.py b/docs/mxdoc.py index a0ec39922f9e..aa7c3831d46c 100644 --- a/docs/mxdoc.py +++ b/docs/mxdoc.py @@ -59,7 +59,8 @@ # 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', '//'), @@ -102,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) @@ -114,9 +115,10 @@ def build_scala_docs(app): dest_path = app.builder.outdir + '/api/scala/docs' _run_cmd('rm -rf ' + dest_path) _run_cmd('mkdir -p ' + dest_path) - scaladocs = ['index.html', 'org', 'lib', 'index.js'] + # '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""" @@ -126,9 +128,9 @@ def build_java_docs(app): dest_path = app.builder.outdir + '/api/java/docs' _run_cmd('rm -rf ' + dest_path) _run_cmd('mkdir -p ' + dest_path) - javadocs = ['index.html', 'org', 'lib', 'index.js'] + 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) + _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""" @@ -138,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""" From b5d5f8836e1e4e9af420e3e101f712c7b48dc4e8 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Wed, 7 Nov 2018 11:13:48 -0800 Subject: [PATCH 4/4] fix exit bug --- docs/mxdoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mxdoc.py b/docs/mxdoc.py index aa7c3831d46c..8570caeaedac 100644 --- a/docs/mxdoc.py +++ b/docs/mxdoc.py @@ -140,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; exit 0) + _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"""