[GitHub] aaronmarkham commented on issue #12518: Documentation indices for Random Samplers incomplete

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

aaronmarkham commented on issue #12518: Documentation indices for Random Samplers incomplete
URL: https://github.com/apache/incubator-mxnet/issues/12518#issuecomment-424889176
 
 
   Hi @asmushetzel I can see what you're seeing.
   In the top-most sections that are overviews, you see specific includes using Sphinx `autosummary`.
   https://github.com/apache/incubator-mxnet/blame/master/docs/api/python/symbol/symbol.md#L589-L598
   ```
   .. autosummary::
       :nosignatures:
       mxnet.symbol.random.uniform
       mxnet.symbol.random.normal
   ...
   ```
   
   But near the end in the API reference section you see a variety of blanket includes of all `members` or `imported-members` or `special-members`:
   https://github.com/apache/incubator-mxnet/blame/master/docs/api/python/symbol/symbol.md#L702-L713
   ```
   .. automodule:: mxnet.symbol.random
       :members:
   ```
   
   I'm thinking this is the cause of why some ops are missing in the overview sections. I see a lot of this through the API docs: specific callouts instead of including all of the members. I get that in some cases you want to organize the output, but this means things don't get included in the automatically generated docs. I wonder how one can find the other blind spots without doing side-by-side comparisons on everything.
   
   However, comparing things directly isn't exactly easy even if it is slow and painful. I was baffled by the lack of results in GitHub for `sample_uniform` - only C operators and nothing in Python. This is found under `_sample_uniform` once you vector in on some unique comments, and that's because you pointed out things were missing. Thanks for that! This will be a great thing to fix.
   

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