[0] https://docs.scipy.org/doc/numpy-1.12.0 [1] https://matplotlib.org/contents.html
The one thing I'd like to see is more examples. Sometimes a quick demo of a function is all that's required for basic use.
The actual software design is great as well, single-handedly changed my mind about ORMs.
I think the Exim spec is pretty much the gold standard for reference documentation, but they need a separate user-friendly introduction too (there was a separate paper book at one point).
I've heard that every comment in code follows the same pattern: every line becomes smaller and smaller. There is a lot of dedication in this project.
There is no perfect documentation, because you can't predict your audience. I document code in such a way as to make it easier for myself to go back to it. I've kicked myself too many times to count where I didn't document something; went back to code, found it confusing, went to find out who wrote it only to discover it was me.
Document your code for yourself.
If you aspire to have it used by other people, it is still good advice, but only a first step. The next step is to test the documentation. Have someone run through your intro tutorial and see both:
- How hard is the tutorial to work through
- How well does it help them build a mental model of the major interfaces of the project.