Scala API docs examples and discussion content & render inaccuracies

[aaronmarkham]

Description

The Scala API docs are generated using sources that have examples that are pythonic or otherwise not Scala example code. Also scaladocs isn't able to render the rst code that is extracted from the other sources.

Rather than include this info that doesn't render properly and is out of context, it would be better to link to the source material where it renders properly and makes sense in its original context.

Example:
BilinearSampler would still have the inputs and returns info, but the detail would point to the BilinearSampler Python API source docs.

@andrewfayres @zachgk @lanking520

[aaronmarkham]

Example current display on the Scala API:

[aaronmarkham]

Original discussion begins with this PR and associated issue: #13210

[zachgk]

@mxnet-label-bot add [Doc, Scala]

Thank you for submitting the issue! I'm labeling it so the MXNet community members can help resolve it.

[piyushghai]

@aaronmarkham @zachgk Did the PR : #13210 help in resolving this issue ?
If yes, can we close this issue ?

[zachgk]

No, this issue concerns a separate problem.

In the documentation for the scala NDArrayAPI and SymbolAPI, we currently make method documentation for all of the operators by simply taking the python documentation and examples and including it as a code block (pre tag). You can see it at https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.NDArrayAPI$ . However, the docs are sphinx rst code including sphinx directives, latex code, and modifiers (such as **bold text**). None of this is interpreted by scala docs and we just show the docs source verbatim. In addition to being somewhat difficult to read, there are examples that are written in python code which might be unexpected to users since it is in scala documentation. Some users might find this useful as it can be included in the IDE and makes the somewhat imperfect documentation quickly accessible. It may also be confusing for users since it requires reading rst source and is not correct for scala. Another option is to favor correctness and replace the hardcoded example with a link to the equivalent python function docs since they are parsed and clearly python. But, this is less accessible for the advanced users. Any thoughts on what we should do?

I raised the issue on the mxnet-scala slack channel on December 4th but there was no discussion or clear resolution to the question