The CI build is failing because of two reasons:

1. I forgot to define a variable.

2. It is failing the example of an error. I am not sure if we can skip certain code blocks during testing.

      >>> x = np.array([[1, 2], [3, 4], [5, 6]])
      >>> x[np.array([1, -1])]
      array([[3, 4],
            [5, 6]])
      >>> x[np.array([3, 4])]
      IndexError: index 3 is out of bounds for axis 0 with size 3`
   

Hi @Mukulikaa - sorry for the delay!

A couple of high-level comments:

• I think the general idea of moving content from the user doc to the reference doc makes the user doc a little bit out of place as a "basics". In fact, reading it I kind of felt like it was way more advanced than the reference page, just because there are no examples and it is very abstract.
• The original Indexing basics page kind of reads like a verbose how-to; I think it's useful for beginners to have that kind of entry-level content about indexing. Many people are coming from other programming languages and get tripped up on slicing, advanced indexing etc.
• The original Indexing reference is to me very much an Explanation and, to me, should live in the Fundamentals section.
• There are some indexing examples in Quickstart and the Absolute Beginners documents, but they are also mixed in with a lot of other stuff.

So, here's my suggestion (but others may very well disagree!):

• Keep your edits to the doc/source/reference/arrays.indexing.rst document but move it to the fundamentals section;
• Maybe merge the basics (doc/user/basics.indexing.rst) document into the arrays.indexing.rst document
• Create an indexing how-to, with clear and concise examples of indexing operations.

Of course the how-to would come in another PR, but to me it makes more sense to organize things that way.

Thoughts?

cc @mattip @rossbar

Thanks, @melissawm! I agree with all of your suggestions. I moved all the information to the reference guide doc because it was suggested here and I assumed users would prefer that. But I agree if we were to strictly follow Diataxis then we should move the doc to the Fundamentals.

I am also in the process of making a list of use-cases for the how-to 🙂.

So, right now here's what we have:

• In the root of NumPy Fundamentals we have Indexing basics
• From Indexing basics, we can reach Indexing which is actually like a stub with other references for more complete documents.
• Now, in the reference docs, inside The N-dimensional array we also have a subheader "Indexing arrays", which again just points to Indexing

I'm wondering if it would just be better to remove the Indexing arrays section in the "N-dimensional array" page, and put that sentence directly into Indexing.

Another option would be to lose the Indexing page altogether; I'm struggling to understand if this is needed after the current changes.

Oh and another point: the "Indexing basics" page is not basic at all :) I'd change its title to Indexing or "Indexing on ndarrays", something like this.

Another option would be to lose the Indexing page altogether; I'm struggling to understand if this is needed after the current changes.

I was also thinking about this because I agree that this doc is a stub. However, I felt that having that doc clearly visible in the sidebar makes it more accessible to someone who directly refers to the reference doc instead of the user guide (experienced users maybe?). So I was thinking if we could replace the stub with Indexing routines which would link to the doc in the user guide. It will look something like the ufuncs reference doc I restructured recently.

I'd change its title to Indexing or "Indexing on ndarrays", something like this.

I agree, we can change it to "Indexing on ndarrays" to avoid any clash.

I'm wondering if it would just be better to remove the Indexing arrays section in the "N-dimensional array" page, and put that sentence directly into Indexing.

I don't have any particular opinion on this so I'm happy to amend it the way everyone thinks is best!

I am not sure if the CI failure is unrelated.

This is fixed on main but unfortunately circleCI does not "merge-from-main" before building a PR. So you will have to get those changes into this PR manually. I would recommend rebasing the PR on top of main, you could also merge main into the PR. A rebase would look like

git checkout main
git pull
git checkout indexing-docs-merge
git rebase
# if there are conflicts, you need to do some cycles of 
# git status
# <see what has conflicts>
# fix the file: look for sections with "<<<<", "=====", ">>>>>" and resolve the conflicts
# git add <file>
# git rebase --continue
git push -f Mukulikaa

Here is the rendered page.

Hmm, I started going through the content, but on second thought maybe that should be left for a follow-on PR. This does such a great job moving the pieces around it would be a shame to delay merging it on smaller details.

If it is easier to leave comments on this PR for the changes required, I am happy to continue the work on this PR itself. As I am actively working on this it wouldn't cause much delay I think. 🙂

Thank you for your comments @rossbar! I think I omitted some examples to reduce the length of the document but I agree that they should be included if they make the concepts clearer.

Hi @rossbar, I've tried to incorporate the changes you suggested. Let me know if there are any other suggestions!

The latest commit which changed a link name made me start thinking about a side-effect of this refactoring: it might break existing links. I took a look at the nitpicky CI run results for internal consistenc. It seems the WARNINGS: with the word "index" in them (like the See Also section of expand_dims and missing numpy.lib.index_tricks in the second paragraph of np.choose) existed before this PR and no new ones appeared. But there may be content out there that does rely on the older links. Should we make an effort to preserve them where possible?

Thanks @Mukulikaa. Let's put this in, we can make more changes if it turns out we broke links by rearranging things.