[GitHub] aaronmarkham opened a new pull request #12871: fix broken Python IO API docs

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

aaronmarkham opened a new pull request #12871: fix broken Python IO API docs
URL: https://github.com/apache/incubator-mxnet/pull/12871
 
 
   ## Description ##
   Fixes #12854 
   * This PR manually specifies members of the IO module so that the docs will render as expected. This is workaround in the docs to deal with a bug introduced in the Python code/structure since v1.3.0. See the comments for more info.
   
   * This PR also fixes another issue that may or may not be related. Cross references to same-named entities like `name`, `shape`, or `type` are confusing Sphinx and it seems to just link to whatever it last dealt with that has the same name, and not the current module. To fix this you have to be very specific. Don't use `type`, use `np.type` if that's what you want. Otherwise you might end up with `mxnet.kvstore.KVStore.type`.
   
   I mapped these to aliases, so the docs still have a shorthand reference. 
   ```
   .. _name: mxnet.symbol.Symbol.name
   .. _shape: mxnet.ndarray.NDArray.shape
   ```
   So you will see me use `name_` in the docstring, and that will link up to the `_name` alias for `mxnet.symbol.Symbol.name` that is defined at the end of the documentation page's rst code.
   
   **This is important for any future modules** - that they recognize this issue and make efforts to map the params and other elements.
   
   ## Checklist ##
   ### Essentials ###
   Please feel free to remove inapplicable items for your PR.
   - [x] Changes are complete (i.e. I finished coding on this PR)
   - [x] Code is well-documented
   - [x] To the my best knowledge, examples are either not affected by this change, or have been fixed to be compatible with this change
   
   ### Preview
   **To see the APIs populated:**
   Go to the 1.3.0 docs: http://mxnet.incubator.apache.org/versions/1.3.0/api/python/io/io.html#data-iterators
   Then switch to master. See how links are not there, and down in the API Reference none of those things are present.
   Now go to my preview: http://34.201.8.176/versions/1.3.1/api/python/io/io.html
   
   **To see the parameter mapping:**
   It's broken on master and not even visible, but you can look at 1.3.0.
   http://mxnet.incubator.apache.org/versions/1.3.0/api/python/io/io.html#mxnet.io.DataDesc.get_list
   Note that the mappings pretty much work, but type seems messed up because I doubt it is intended to be from `kvstore`. Now look at my preview:
   http://34.201.8.176/versions/1.3.1/api/python/io/io.html#mxnet.io.DataDesc.get_list
   
   
   ## Comments ##
   Changes that have come in since v1.3.0 have caused some havoc with Sphinx. This could be a bug in the Python code or maybe Sphinx needs things to be a certain way to function properly.
   * It can't distinguish between methods of the same name
   * It can't use automodule to fetch all members automatically 
   **This means a lot of the docs are currently broken!** I ask that some more people take a look because it could be a minor change in the Python versus having to go through and update every single bit of docs and doc strings in each module.
   
   You can see in this PR what had to be done just for one module. Note the `recordio` hasn't been touched and Sphinx renders the docs just fine.
   http://mxnet.incubator.apache.org/versions/1.3.0/api/python/io/io.html#data-iterators
   
   

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