Python API docs issues

[Aaron Markham <aa...@gmail.com>]

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