Overview documentation

[daniel-vainsencher]

I at least often find myself wondering "does ndarray support this? where should I look for it?".

ndarray has not bad reference documentation, but not enough of an overview that points into the reference.

I think overview documentation should explain as soon as possible what the library does, give examples of use of the core features, and relate the core design ideas necessary for using it (including linking to any terms that are going to come up, including the main types, traits etc. The crates.io entry [1] does the first well, but the module documentation [2] is a bit mixed up:

• Mentions N-dim array
• Skips forward to defining some main types (without explaining the design)
• Goes back to state the core features (no examples, though)

I would put all of the overview information in the module docs, leaving details to e.g., the ArrayBase page.

[1] https://crates.io/crates/ndarray
[2] https://bluss.github.io/rust-ndarray/master/ndarray/index.html

[bluss]

The main reference is I guess the documentation for the type https://bluss.github.io/rust-ndarray/master/ndarray/struct.ArrayBase.html

It needs a few more sections, for example for:

• Array views

[pkgw]

I'd just like to give a +1 for this. The API reference is great but I also believe it'd be very useful to have a more pedagogical document.

[ZuseZ4]

I agree on that, I am unsure whether I would have continued learning Rust without having the book as a great explanation on how and why things work.

I've been reading through the docs of ndarray, but I felt like there would be missing something comparable to the book. The docs itself are great, but for me they are just a bit to much, since I'm not that experienced with Rust. I guess other people might know this feeling.

Lets take a.dot(&b) as one example, with a and b having n elements, represented as
Rust Vec vs. Array1 vs. Array2 1xn matrx
I read that Array1 is stated to have some convenience functions over higher-order arrays.
But having n and m as Array1 with length n and m I had serious issues to calculate n.dot(&m.t()) = nxm to get an Array2 as result.
All of those Elements probably have good reasons to behave the way they do, but having to pick up those reasons from some place in the docs was hard for me.

Another issue was the support on my issues.
On normal questions in rust-beginner I'll usually get an answer within a minute or so.
Getting my current project running with ndarray is already a matter of multiple days since they were only few people answering my questions on ndarray.
Is there a reason why we don't have a specific discord channel for ndarray?
For me it would make sense since matrix/vector manipulation is generally an important topic, while already being a bit to much for a beginner channel. #Science-and-AI makes use of ndarray, but asking there doesn't feel right.

As a last point, I'll hopefully finish my manual implementation of Neural Networks in the next days.
Based on the help I got and some questions where I still need help I would like to add the result to the ndarray cargo docs to give something back.
I would like to follow this sub-chapter with my general layout, rather than just copying the code with a few comment lines into the example folder.
https://doc.rust-lang.org/stable/book/ch07-02-defining-modules-to-control-scope-and-privacy.html
I have no experience with writing such docs, so feedback would be appreciated.

_ @LukeMathWalker in #462 (comment)_
has mentioned that writing such explanations in doc.rs might not be too easy, but maybe we can copy some part of the book? I'm just unsure how to set that up.

Since this became longer than expected, &tl;dr:

1. Create a small copy of the book with 2 or 3 chapters explaining when to use which Datatypes and why some operators might not work the way one would expect based on python experience.
   Basically https://docs.rs/ndarray/0.13.1/ndarray/doc/ndarray_for_numpy_users/index.html#rough-ndarraynumpy-equivalents with a bit more examples/explanations instead of simple tables.

2. Discord channel for ndarray usage.
   To not pollute Science-and-AI and reduce waiting time compared to the beginner channel.

3. Add longer examples with more background rather then just code with a few comment lines.
   Taking this as motivation: https://doc.rust-lang.org/stable/book/ch07-02-defining-modules-to-control-scope-and-privacy.html
   I'll try to present a version of my neural network for discussion if someone is interested.

Please let me know what you think about those 3 points.
Especially since ndarray is a more specialized tool than Rust itself I wonder if someone might argue that we shouldn't take the book as motivation.

I can create extra issues for those sub-points if people are interested.
But since we already have a few discussions about docs open, I didn't wanted to start with another issue to summarize the existing posts: https://xkcd.com/927/

[ZuseZ4]

I guess after 3 days there won't be to many updates anymore, so I created the Discord Channel "Rust ndarray"
https://discord.gg/mEKDAhT

Once you enter I'll put you as admin @bluss.
Hope we will find sufficient users so it eventually becomes useful.
When creating the PR for point 3. I will also search for a place on your main page to add it, if you don't mind?
Oh and feel free to propose a nicer image for the channel, it was the first more or less suitable under an appropriate license I could find.

And since I'm already here, more as a note to myself, it might be useful to find a way to automatically link to the current version of the doc from the first side. The links e.g. to ndarray for numpy users are outdated: https://docs.rs/ndarray/0.12.1/ndarray/
Shouldn't matter too much, anyway.