direction for documentation across various APIs that share common doc source

[Aaron Markham]

Hi everyone,
A recent issue and pending PR has brought a thorny docs situation to
my attention again and I'd like to hear from the community on how to
proceed.
We currently get some of the docs for the Python API pulled out of .cc
files. Other APIs also get docs from there, or pull the Python docs to
autogenerate their docs. This presents some problems:
1. (Some of) The code examples provided don't run when you copy and
paste them. [1]
2. The code examples that show up in other APIs won't work as the code
is Python and for (many/complicated) statements the syntax can be
wrong.

When I try out something new and go for the hello world example or
browse around I do expect the docs' code examples to work. If they
don't, well, that's a bad sign and I move on to another project. I'd
like for new users to have a great experience no matter what language
they use.

One fix is to go ahead a be "Python 1st" and make sure the code
executes. This route is proposed in a PR for some NDArray operators.
[2] As I mention in the PR comments, this has the drawback of being
very specific to Python and the psuedo-code, for what its worth,
showing up in Scala docs (for example) will be much more obviously out
of place. If I were an Scala person, I'd probably find this
irritating. The same goes for R.

So... what should we do? Here are some ideas:
a) I thought about providing different examples in the .cc code, one
for each language and then making sure those are parsed out properly
when the APIs are generating their docs. I'm not sure how feasible
this is.
b) I thought that it would be nice if each operator had a wrapper for
each language API, and this is where the example payload resides.
Maybe docstrings go here too or the common docstrings just bubble up
from the cc file. The benefit is that changes for a specific language
remain in those packages and don't touch the shared core files.
c) Another route is to keep the examples in the .cc files pseudo-code,
but then also make sure each language has real examples in their docs.
Then, any code block that's in the docs now that won't execute should
be changed to a preformatted text block so people don't confuse it
with functional code.

I really don't like any of these options as they each sound like ton
of work and difficult to maintain. Are there any projects that solve
this problem in some elegant and efficient way?

Cheers,
Aaron

[1] https://github.com/apache/incubator-mxnet/issues/14232
[2] https://github.com/apache/incubator-mxnet/pull/14243

[RFC] Introducing NumPy-compatible coding experience in MXNet

[Jun Wu]

Dear Community,

We have published a post here
 requesting for
comments on our proposal of improving MXNet usability. We'd like to hear
the thoughts and suggestions from the community and welcome any form of
contribution to make MXNet's usability as great as its performance.

Thanks,
MXNet developers from AWS

Link to RFC: https://github.com/apache/incubator-mxnet/issues/14253

Re: Help with the Clojure release jars

[Carin Meier]

The jars have been cleaned up. Thanks for the help everyone.

On Sun, Feb 24, 2019 at 7:27 PM Carin Meier  wrote:

> I also updated my instructions with big red letters not to do that again
> and documented how to fix it in a section at the bottom if for some reason
> it happens to the Clojure or Scala jars
> https://cwiki.apache.org/confluence/display/MXNET/Clojure+Release+Process.
>
>
> On Sun, Feb 24, 2019 at 7:18 PM Carin Meier  wrote:
>
>> Here is the link to the INFRA ticket
>> https://issues.apache.org/jira/browse/INFRA-17905
>> and the sonatype one https://issues.sonatype.org/browse/OSSRH-46500
>>
>> On Sun, Feb 24, 2019 at 6:52 PM Carin Meier  wrote:
>>
>>> Ok. I will open an INFRA ticket for it and keep this thread updated.
>>>
>>> On Sun, Feb 24, 2019 at 6:49 PM Naveen Swamy  wrote:
>>>
 Since we release and vote on source and these were not a part of the
 voting, I think it's ok do it independently I.e proceed with clean up
 followed by rerelease so it won't impact closure users

 > On Feb 24, 2019, at 3:46 PM, Carin Meier 
 wrote:
 >
 > Yes. It looks a bit confusing because I have a copy for the jars both
 in
 > staging and in releases since after I hit release, I created them
 again
 > while my brain was trying to figure out what went wrong.
 >
 > My understanding after talking with #asfinfra is that we would have
 to:
 > 1) Create an infra ticket to delete it from repository.apache.org
 > 2) Create a ticket with issues.sonatype.org to delete it from central
 >
 > We can either
 > -  Wait and let them be until the vote concludes, if the vote doesn't
 pass
 > I can make the tickets to delete them.
 > - Create the tickets and delete them now.
 >
 > Let me know if this is what we want to do and I will kick off the
 process.
 >
 > -Carin
 >
 >> On Sun, Feb 24, 2019 at 6:39 PM Naveen Swamy 
 wrote:
 >>
 >> Did you close the repo? In my understanding, the repo(*.Apache.org)
 is
 >> under infra's control, so we porbably have to create a infra ticket,
 last
 >> time I wasn't able to delete( luckily it was in staging, so I
 abandoned and
 >> released to staging again.)
 >>
 >>> On Feb 24, 2019, at 2:36 PM, Carin Meier 
 wrote:
 >>>
 >>> From the #infra channel, the options to fix seem to be that it can
 be
 >>> deleted from the repository.apache.org, but we'd need to talk to
 >> sonatype
 >>> about getting it removed.
 >>>
 >>> I'm not exactly sure where we are in the voting process for
 release, so
 >>> please let me know how everyone would like to proceed.
 >>>
 >>> Sorry again and I'll take steps to make sure that it won't happen
 again.
 >>>
 >>> Best,
 >>> Carin
 >>>
  On Sun, Feb 24, 2019 at 5:19 PM Carin Meier 
 >> wrote:
 
  It appears I did accidentally release them :(
 
  I'm chatting with Infra in the slack room to see if there are any
 fixes.
  If anyone has any other ideas please let me know.
 
 > On Sun, Feb 24, 2019 at 4:35 PM Carin Meier >>> >
 >> wrote:
 >
 > I was wondering if someone could help me verify if I accidentally
 > released the Clojure jars.
 >
 > Background:
 > I was creating and testing the Clojure jars for staging according
 my my
 > instructions[1].
 > I hit the close button on the repository but I didn't see it
 updated at
 > the link
 >
 >>
 https://repository.apache.org/content/repositories/staging/org/apache/mxnet/contrib/clojure/clojure-mxnet-linux-cpu/1.4.0/
 > - so I hit the release button.
 >
 > Last time I did a release, I remember I had to explicitly hit the
 > "promote" button to get it promoted to maven central at the
 release
 >> time,
 > but now I'm not sure.
 >
 > So could someone please help me:
 > 1) Figure out if I accidentally released it by mistake
 > - there are 3 jars: The clojure linux-cpu, linux-gpu, and osx-cpu
 > 2) If I did, please tell me how/if I can fix it (and sorry of
 course)
 > 3) Please let me know any corrections so I that I can update my
 process
 > instructions and make sure it doesn't happen again.
 >
 > Thanks,
 > Carin
 >
 
 >>

>>>

MXNet Meetups

[Naveen Swamy]

A user driven meetup in Copenhagen on April 4th, if any of you are in the
area. check it out

a) Introduction to Gluon NLP & CV and ONNX
b) MXNet to ONNX to ML.NET [1]

Thanks Cosmin for your passion to MXNet, organizing and leading the meetup
group.

Another Meetup today in Palo Alto,
Deep Learning With MXNET On Video: Ring & Xbox video demos [2]

[1] https://www.meetup.com/meetup-group-bdEUVQHL/events/258352270/
[2] https://www.meetup.com/deep-learning-with-mxnet/events/258901722/ (This
is organized by Marcelo and others.)