Documentation edit for matshow function

[Impaler343]

PR summary

This changes the documentation of the matshow function, making it clearer as to which dimension corresponds to which number in the array passed to the function. The convention used is standard practice, where the first number(rows) corresponds to the length of the vertical column and the second number(columns) corresponds to the length of the horizontal column.
Closes #27852

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• [N/A] new and changed code is tested
• [N/A] Plotting related features are demonstrated in an example
• [N/A] New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

[timhoffm]

I would like the row, column terminology to be included somehow as that’s how matrices are usually described.

[jklymak]

Yes it's confusing to call a row a "horizontal column". See https://en.m.wikipedia.org/wiki/Row_and_column_vectors

[Impaler343]

Changed it up to include row and column terminology. Please check. On another note, why are certain checks not passing? As I only changed the documentation right?

[tacaswell]

The failing tests were unrelated (a new version of pytest broke us).

[Impaler343]

I see

[tacaswell]

@Impaler343 I took the liberty of merging my own suggestion for adding spaces, did not seem worth a back-and-forth on, hope you do not mind.

[Impaler343]

Absolutely fine with it, got a lot to learn!

[tacaswell]

I think there is a reading where the original text was correct (if you pick out a single row, then you move horizontally as you scan through the data in that row), but it also has the opposite reading (as you scan through the rows (at a fixed column) you move horizontally). I do not think either reading is clearly "wrong", so this rewording is an improvement.

[timhoffm]

Suggested change

	Display an array as a matrix in a new figure window.
	Display a 2D array as a matrix in a new figure window.

[timhoffm]

Sorry to bikeshed again, but IMHO this is logically incorrect. The index has no direct relation to the height - it's only that first index and height are associated with the same direction (=vertical). Do you have any reservations on my original proposal:

    The indexing is ``(row, column)`` so that the first index runs vertically
    and the second index runs horizontally in the figure.

[anntzer]

I would boringly reuse (nearly) the documentation for Axes.matshow:

Plot the values of a 2D array as a color-coded image in a new Figure window.

The array is shown as it would be printed, with the first row at the top. The aspect ratio...

[timhoffm]

I would boringly reuse (nearly) the documentation for Axes.matshow:

Plot the values of a 2D array as a color-coded image in a new Figure window.

The array is shown as it would be printed, with the first row at the top. The aspect ratio...

I believe it's important to mention the term "matrix" as 1) it's gives a certain intuitive expectation of the layout even without reading the detailed explanation and 2) it connects to the method name. One could amend your version with that, but I find it then equal to the current version in this PR. So I would just merge without bike shedding further. @anntzer please speak up if you feel strongly about your proposal.

[anntzer]

@timhoffm I don't really mind either way. If anything I'd rather try to push users away from matshow()...

[timhoffm]

I've fixed the squash and rebased on main. Took the liberty to push back to your branch.

[Impaler343]

Wow, could you tell me what you did? I'm assuming you made another branch and pushed it to this one?

[timhoffm]

1. Checked what's on this branch.
2. Decided to go with cherry-picking instead of interactive rebase given that only a few commits of this branch were relevant.
3. Created a new branch and cherry-picked the relevant commits. For one of them with only partly relevant content (likely from a merge), I created a new commit instead (while one can cherry-pick partial commits, just copying the one relevant code change and committing that was easier).
4. Squashed the commits in the new branch.
5. Created a backup branch for this branch.
6. Reset --hard this branch on the new branch.
7. Force pushed.

It would have been easier to just copy the docstring and make a new commit with that, because the change is just in one place. But that would have meant that it's my commit and your attribution would have been lost. So, I've taken the more general route.

[timhoffm]

Thanks @Impaler343 and congratulations on your first contribution to Matplotlib! 🎉 We hope to see you back.