You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.
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.
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
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
The text was updated successfully, but these errors were encountered: