Hello everyone! I'm writing this note to raise awareness about some issues I'm seeing with the Python API docs. While some of the issues can be traced back prior to v1.3.0, the biggest issue of docs not rendering is fairly recent. At a high level, Sphinx (our Python API docs generator) is getting confused with a couple of things: 1. Folder changes (moving optimizer.py to /optimizer/, and io.py to /io/, etc.) 2. Ambiguous references (where ndarray, type, shape, name, etc are declared in different modules)
This is leading the Python docs to link up to the wrong place, or not link up at all, or not generate at all. If you didn't know, most of the API reference is auto-generated with about two lines of rst that invokes Sphinx to do its thing. Except now Sphinx is not doing what it's supposed do. I've done a couple of workaround to fix the docs in areas that were reported broken - by manually specifying the members of the API that should be generated and manually linking up parameters, but I get this nagging feeling that this could be fixed upstream. The init functions, the importing, or ...? I don't really know, but Sphinx is unhappy and the docs are suffering. Or maybe since the project is growing, we have give Sphinx a little more TLC and be very good at being specific in the documentation. I've documented what I've been seeing in some recent PRs and issues. * Start here with the Python IO API since I've provided several links to tour the two "Sphinx confusion" issues I previously mentioned. https://github.com/apache/incubator-mxnet/pull/12871 * I also reported Sphinx not being able to access shorthand methods in other PR where I fixed the test_utils and visualization docs. Looks at the comments. https://github.com/apache/incubator-mxnet/pull/12455 Note that mxnet.viz doesn't work but mxnet.visualization does... for Sphinx. But everyone else can use mxnet.viz. What's up with that? I found this pretty strange. * This happened again with the ONNX import_model function. I deployed a workaround so the ONNX docs were at least functional. It is reported here: https://github.com/apache/incubator-mxnet/issues/12318 * Ndarray docs are messed up right now. Reported here: https://github.com/apache/incubator-mxnet/issues/12829 I can probably fix the Ndarray API docs using the same pattern I used for the IO API, but I don't want to go down this path too far when there might be a simple solution. Otherwise, it seems pretty clear that every .py file and every .md file for the Python API will need some updating. Thoughts? Any Sphinx whisperers out there? Thanks! Aaron