Improve documentation page for "Tensor"

[PtiLuky]

Improve "Tensor" page documentation

Checklist

• Confirmed that run-checks all script has been executed.
• Made sure the book is up to date with changes in this PR.

Changes

• fixed some mistakes in the documentation (such as sometimes stating "element wise" when it should have been "with a scalar"). Or example code with wrong values shown (for tensor.min_dim_with_indices)
• changed some examples to make them more explicit about the function behavior.
• Developed a bit some function description when text was quite vague.

Things to discuss

This is my first PR, I am new to Burn crate and struggled to understand some functions for which I needed to check directly the code. The goal of this PR is to avoid this for next newcomers!
Also if this PR shall be split in several smaller PRs, please tell me. I didn't feel like I should have made one PR per function documented...

More general remarks about the documentation:

• There is no indications for contributing to documentation in the contribution guide, this is a bit missing, specially for the 2 following points
• The verbs are not consistent, sometimes functions are described with "Does this and that" and sometimes it's "Do this and that", is there any recommendation here? If so making it explicit in the guidelines would be great!
• The usage of the vocabulary rank, dimension, dimensions, size and shape is not always consistent, quite often I found "tensor of dimensions [x, y, z]", the idea is totally understandable here, but in this case the right word is "tensor of shape [x, y, z]", no? I am asking just to know if I should try to be accurate in the vocab for next PR (maybe even replace existing misuses) or if it's not important and should not be changed?

Testing

Visual testing of the generated doc.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.13%. Comparing base (8a6f37c) to head (10ae203).
Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2951      +/-   ##
==========================================
+ Coverage   82.11%   82.13%   +0.01%     
==========================================
  Files         867      867              
  Lines      120268   120268              
==========================================
+ Hits        98763    98781      +18     
+ Misses      21505    21487      -18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[laggui]

Thanks for improving the docs! This might be a common friction point for new users 🙏

I have a couple of comments, lmk what you think.

[laggui]

This is misleading, because expand does not actually repeat the values (which would imply allocating new memory for the repeated output tensor).

[PtiLuky]

Uhm... then I probably did not fully understand this method myself. I will remove this comment to avoid leaving a misleading comment.

[laggui]

Expanding a tensor does not allocate new memory. Instead, it modifies the strides of the tensor to virtually expand it along the specified dimensions.

This is done by setting the stride to 0 for the expanded dimensions, meaning every element along that dimension points to the same memory location. This effectively "repeats" values without duplication.

Hopefully this clears it up a bit 😅

[PtiLuky]

Yes clear (and clever)!

[laggui]

Regarding your other remarks:

More general remarks about the documentation:

• There is no indications for contributing to documentation in the contribution guide, this is a bit missing, specially for the 2 following points

That's a good point! We should probably add at least a small section.

• The verbs are not consistent, sometimes functions are described with "Does this and that" and sometimes it's "Do this and that", is there any recommendation here? If so making it explicit in the guidelines would be great!

I agree, it would be nice to stick to the same pattern / tense for the operations. It's not a big deal, but standardizing the docs would be nice. I don't have any personal preference for the tense, as long as it is clear 😅

• The usage of the vocabulary rank, dimension, dimensions, size and shape is not always consistent, quite often I found "tensor of dimensions [x, y, z]", the idea is totally understandable here, but in this case the right word is "tensor of shape [x, y, z]", no? I am asking just to know if I should try to be accurate in the vocab for next PR (maybe even replace existing misuses) or if it's not important and should not be changed?

Hahah yeah there might be a slight abuse of language in some instances where dimensions/shape/size is used 😬 If you want to improve the docs to disambiguate the usage of these terms, you can do it in another PR 🙂

[laggui]

Thank you for improving the docs 🙂