[MXNET-624] Clojure Package Api Docs for the Website #11574

gigasquid · 2018-07-05T23:21:32Z

Description

Clojure API Docs for the Website

Checklist

Essentials

Please feel free to remove inapplicable items for your PR.

The PR title starts with [MXNET-$JIRA_ID], where $JIRA_ID refers to the relevant JIRA issue created (except PRs with tiny changes)
Changes are complete (i.e. I finished coding on this PR)
All changes have test coverage:
Code is well-documented:
To the my best knowledge, examples are either not affected by this change, or have been fixed to be compatible with this change

Changes

Start of API docs markdown pages for the Clojure Package
Minor tweaks to add rm viz example checked in by mistake and other slight wording tweaks

Comments

The website changes are not linked in so even if the PR is merged it won't be visible yet.

- get rid of getting started since it shows up in codox docs

gigasquid · 2018-07-05T23:22:12Z

@aaronmarkham Here is a start on the Clojure API docs for the website. Feedback is welcome.

gigasquid · 2018-07-06T13:29:25Z

I'm trying to figure out what the docs pipeline is missing. Can you help @nswamy @larroy ?

Could not find artifact org.apache.mxnet:mxnet-full_2.11-linux-x86_64-cpu:jar:1.3.0-SNAPSHOT in clojars (https://repo.clojars.org/)

Command 'cd /work/mxnet/docs/../contrib/clojure-package; lein codox' returned non-zero exit status 1

The command lein codox can't find the scala jars it needs because the make scalainstall has not been run in the environment. I know the make scalapkg has because the scala docs are there. Where is the right place to tie this into the the docs/ ci pipeline?

nswamy · 2018-07-06T18:48:52Z

I am not sure if you got a chance to review this document written by @aaronmarkham https://github.com/apache/incubator-mxnet/tree/master/docs. Right now Scala docs are generated using a Python script here: https://github.com/apache/incubator-mxnet/blob/master/docs/mxdoc.py#L81. You might have to create your own method in this script to execute make scalpkg and make scalainstall

gigasquid · 2018-07-07T11:40:39Z

Thanks - I'll take a look at trying to run the docs locally and get the script working with the clojure package later this weekend

gigasquid · 2018-07-08T17:16:00Z

Yay! the docs pipeline is green now - clojuredocs are being built and included.

nswamy · 2018-07-08T18:50:24Z

this is cool, thanks @gigasquid. i'll await @aaronmarkham to take a quick look and merge after.

aaronmarkham

These are great overall. I have some minor suggestions for formatting and clarity. I'll also need to follow-up with a test build to make sure the dependencies on the build are all working.

aaronmarkham · 2018-07-09T22:09:01Z

docs/api/clojure/module.md

@@ -0,0 +1,235 @@
+# Module API
+The module API provides an intermediate and high-level interface for performing computation with neural networks in MXNet. Module wraps a Symbol and one or more Executors. It has both a high level and intermediate level api.


Second API all caps.

aaronmarkham · 2018-07-09T22:09:39Z

contrib/clojure-package/doc/intro.md

@@ -4,9 +4,8 @@ A clojure package to the MXNet Deep Learning library

 ## Introduction

-MXNet is a first class, modern deep learning library that AWS has officially picked as its chosen library. It supports multiple languages on a first class basis and is incubating as an Apache project.
+MXNet is a first class, modern deep learning library. It supports multiple languages on a first class basis and is incubating as an Apache project.


Does this need repeating deep in the project?

aaronmarkham · 2018-07-09T22:10:11Z

contrib/clojure-package/doc/intro.md

@@ -4,9 +4,8 @@ A clojure package to the MXNet Deep Learning library

 ## Introduction

-MXNet is a first class, modern deep learning library that AWS has officially picked as its chosen library. It supports multiple languages on a first class basis and is incubating as an Apache project.
+MXNet is a first class, modern deep learning library. It supports multiple languages on a first class basis and is incubating as an Apache project.

 The motivation for creating a Clojure package is to be able to open the deep learning library to the Clojure ecosystem and build bridges for future development and innovation for the community. It provides all the needed tools including low level and high level apis, dynamic graphs, and things like GAN and natural language support.


low-level and high-level APIs

aaronmarkham · 2018-07-09T22:10:46Z

contrib/clojure-package/doc/intro.md

@@ -4,9 +4,8 @@ A clojure package to the MXNet Deep Learning library

 ## Introduction

-MXNet is a first class, modern deep learning library that AWS has officially picked as its chosen library. It supports multiple languages on a first class basis and is incubating as an Apache project.
+MXNet is a first class, modern deep learning library. It supports multiple languages on a first class basis and is incubating as an Apache project.

 The motivation for creating a Clojure package is to be able to open the deep learning library to the Clojure ecosystem and build bridges for future development and innovation for the community. It provides all the needed tools including low level and high level apis, dynamic graphs, and things like GAN and natural language support.


Is this section intended to be rendered on the website or just as part of the package source code?

It prints out as part of the packaged api-docs that are generated by lein codox. I didn't really know what to say so I just repeated the intro of the README. I'll remove since it doesn't really shed anything into the api docs

aaronmarkham · 2018-07-09T22:14:34Z

docs/api/clojure/module.md

+(first (ndarray/->vec (first results))) ;=>0.08261358
+```
+
+The module collects and returns all of the prediction results. For more details about the format of the return values, see the documentation for the `predict` function.


Can we link to the docs?

aaronmarkham · 2018-07-09T22:32:41Z

docs/api/clojure/symbol.md

+
+## Group Multiple Symbols
+
+To construct neural networks with multiple loss layers, we can use mxnet.sym.Group to group multiple symbols together. The following example groups two outputs:


mxnet.sym.Group

I will change to group since that is the clojure function.

aaronmarkham · 2018-07-09T22:33:11Z

docs/api/clojure/symbol.md

+```
+
+## Serialization
+ There are two ways to save and load the symbols. You can use the mxnet.Symbol.save and mxnet.Symbol.load functions to serialize the Symbol objects. The advantage of using save and load functions is that it is language agnostic and cloud friendly. The symbol is saved in JSON format. You can also get a JSON string directly using mxnet.Symbol.toJson. Refer to API documentation for more details.


two ways.... mxnet.Symbol.save and mxnet.Symbol.load? (but that's really one way isn't it? What's the other way to save and load?)

Also, can you link to the docs?

aaronmarkham · 2018-07-09T22:36:02Z

docs/api/clojure/symbol.md

+
+## Multiple Outputs
+
+;;To construct neural networks with multiple loss layers, we can use mxnet.sym.Group to group multiple symbols together. The following example groups two outputs:


Why the ;;?
mxnet.sym.Group

That's a code comment in clojure that I forgot to take out when I was porting the code example to this markdown format. Will fix

aaronmarkham · 2018-07-09T22:37:06Z

docs/api/clojure/symbol.md

+```
+
+After you get the ```group```, you can bind on ```group``` instead.
+The resulting executor will have two outputs, one for linerarregressionoutput_output and one for softmax_output.


linerarregressionoutput_output
softmax_output

aaronmarkham · 2018-07-09T22:37:34Z

docs/api/clojure/symbol_in_pictures.md

+# Symbolic Configuration and Execution in Pictures
+
+This topic explains symbolic construction and execution in pictures.
+We recommend that you also read [Symbolic API](symbol.md).


about the Symbolic API prior to attempting this tutorial?

This isn't really a tutorial - it's more of a reference. I copied this verbatim from the Scala side, so any change we make here, we can do in both places if we want to reword

How about We recommend that you read the [Symbolic API](symbol.md) as another useful reference?

gigasquid · 2018-07-09T22:59:46Z

Thanks @aaronmarkham for reviewing and providing feedback. I'll implement the feedback. Feel free after merging to make whatever other tweaks or edits that you think will work best.

aaronmarkham

Thanks for updating things. Looks good! I'll run through it after the merge and make any minor edits.

Clojure Package Api Docs

gigasquid added 6 commits July 4, 2018 13:11

rm visualization example output checked in by mistake

1c901e8

add Kovas to special thanks

3df36b8

fix up tutorial example with right namespaces

2344191

- get rid of getting started since it shows up in codox docs

start on clojure api docs

ca466ba

tweaks in wording

0220ead

tie in building of clojure docs

f3fc627

gigasquid requested a review from szha as a code owner July 5, 2018 23:21

gigasquid changed the title ~~[MXNET-624] Clojure Package Docs Api for the Website~~ [MXNET-624] Clojure Package Api Docs for the Website Jul 5, 2018

fix typo

f22ec27

run scalapkg and scalainstall for clojure package

4dbc9de

fix clojurepath

d515b2d

aaronmarkham reviewed Jul 9, 2018

View reviewed changes

gigasquid added 2 commits July 9, 2018 19:35

feedback from @aaronmarkham

764968c

rewording feedback from @aaronmarkham

e0d8452

aaronmarkham approved these changes Jul 10, 2018

View reviewed changes

nswamy merged commit 7a6e8de into apache:master Jul 10, 2018

XinYao1994 pushed a commit to XinYao1994/incubator-mxnet that referenced this pull request Aug 29, 2018

[MXNET-624] Clojure Package Api Docs for the Website (apache#11574)

91fd67e

Clojure Package Api Docs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[MXNET-624] Clojure Package Api Docs for the Website #11574

[MXNET-624] Clojure Package Api Docs for the Website #11574

gigasquid commented Jul 5, 2018

gigasquid commented Jul 5, 2018

gigasquid commented Jul 6, 2018 •

edited

Loading

nswamy commented Jul 6, 2018

gigasquid commented Jul 7, 2018

gigasquid commented Jul 8, 2018

nswamy commented Jul 8, 2018

aaronmarkham left a comment

aaronmarkham Jul 9, 2018

aaronmarkham Jul 9, 2018

aaronmarkham Jul 9, 2018

aaronmarkham Jul 9, 2018

gigasquid Jul 9, 2018

aaronmarkham Jul 9, 2018

aaronmarkham Jul 9, 2018

gigasquid Jul 9, 2018

aaronmarkham Jul 9, 2018

aaronmarkham Jul 9, 2018

gigasquid Jul 9, 2018

aaronmarkham Jul 9, 2018

aaronmarkham Jul 9, 2018

gigasquid Jul 9, 2018

gigasquid Jul 9, 2018

gigasquid commented Jul 9, 2018

aaronmarkham left a comment

		@@ -0,0 +1,235 @@
		# Module API
		The module API provides an intermediate and high-level interface for performing computation with neural networks in MXNet. Module wraps a Symbol and one or more Executors. It has both a high level and intermediate level api.


		## Group Multiple Symbols

		To construct neural networks with multiple loss layers, we can use mxnet.sym.Group to group multiple symbols together. The following example groups two outputs:


		## Multiple Outputs

		;;To construct neural networks with multiple loss layers, we can use mxnet.sym.Group to group multiple symbols together. The following example groups two outputs:

[MXNET-624] Clojure Package Api Docs for the Website #11574

[MXNET-624] Clojure Package Api Docs for the Website #11574

Conversation

gigasquid commented Jul 5, 2018

Description

Checklist

Essentials

Changes

Comments

gigasquid commented Jul 5, 2018

gigasquid commented Jul 6, 2018 • edited Loading

nswamy commented Jul 6, 2018

gigasquid commented Jul 7, 2018

gigasquid commented Jul 8, 2018

nswamy commented Jul 8, 2018

aaronmarkham left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gigasquid commented Jul 9, 2018

aaronmarkham left a comment

Choose a reason for hiding this comment

gigasquid commented Jul 6, 2018 •

edited

Loading