[GitHub] aaronmarkham commented on issue #12657: Scala doc issue

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

aaronmarkham commented on issue #12657: Scala doc issue
URL: https://github.com/apache/incubator-mxnet/issues/12657#issuecomment-424450157
 
 
   @lanking520 It appears that the impacted pages are not a "normal" scaladocs as they are generated during the "macro" stage. Refer to this comment:
   https://github.com/apache/incubator-mxnet/blob/master/scala-package/macros/src/main/scala/org/apache/mxnet/APIDocGenerator.scala#L27-L31
   ... where it states the NDArrayBaseAPI and SymbolBaseAPI are generated in this way.
   
   Looking at the output you can see that the rst isn't being parsed properly. I'm not sure where this "macro" code is, but that's where I'd look and see if something is breaking the rst. The rst is then going to be parsed Sphinx during the docs build. The scaladocs step with Sphinx generates massive amounts of warnings and errors, so tracking this down will be not fun, but I'm pretty sure it can be troubleshooted by running the [docs build](https://cwiki.apache.org/confluence/display/MXNET/How+to+Build+the+Website) and tinkering with that macro step's output. Maybe this would be a good opportunity to fix some of those scaladocs errors, so troubleshooting this area is not like searching for a needle in a haystack.
   
   Here are the broken pages:
   * https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.SymbolAPI$
   * https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.SymbolAPIBase
   * https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.SymbolBase
   * https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.NDArrayAPI$
   * https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.NDArrayAPIBase
   * https://mxnet.incubator.apache.org/api/scala/docs/index.html#org.apache.mxnet.NDArrayBase
   

----------------------------------------------------------------
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