[GitHub] zachgk commented on issue #13308: Scala API docs examples and discussion content & render inaccuracies

[GitBox <gi...@apache.org>]

zachgk commented on issue #13308: Scala API docs examples and discussion content & render inaccuracies 
URL: https://github.com/apache/incubator-mxnet/issues/13308#issuecomment-454217917
 
 
   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

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services