DOC: Improve the docstring of argsort.

[vsnupoudel]

Updated the docstring for argsort to make it hopefully more clearer

[rkern]

The general docstring convention we (and most other Python packages) follow is to have the first paragraph be a one-line sentence. More detail like this should be in the following paragraphs. We already describe this in prose in the subsequent paragraph, so I would expand on this there.

When you include inline code examples, we use double-backticks to make sure that they get rendered with code fonts appropriately.

The returned indices can then be used as ``a_sorted = a[returned indices]`` which...

Instead of a[returned indices], I would explicitly use a[np.argsort(a)] to make it valid code. Adding an example in the Examples section that does this to demonstrate how these indices relate to the sorted array would be good. Currently, we just show the indices rather than make the explicit connection to the sorted array.

[melissawm]

Not sure what's going on with CI but it's unrelated to this PR.

[charris]

@vsnupoudel Please implement @rkern's suggestion. Also keep lines < 80 characters in length.

[mattip]

I am inclined to close this. The added information does not enhance what is already in the Returns clause.

[rkern]

We get enough "bug reports" of argsort() not returning the "correct" results that I think we do need to improve the docstring somehow. Moving the clarifying example up from Returns to the main body of the docstring is probably the right call.

@vsnupoudel As mentioned, code snippets (and references to variables in those snippets) need to be quoted with double-backticks for proper formatting. See how we do it in the Returns section.

[vsnupoudel]

And an example right after the one liner at the top would be nice. Maybe I wil modify the first example as well.

[rkern]

By the way, by "clarifying example", I just meant the inline a_sorted = a[np.argsort(a)], which I think is sufficient to give the gist without showing any specific output. I think we try to keep ">>>" examples down in Examples. But maybe that's just a rule in my head. I do think a new example which does show the result of a[np.argsort(a)] down in Examples would help, too.

[rkern]

The point of these examples is to show the output. I would just show the result of x[np.argsort(x)] instead of these two examples.

[charris]

This PR was against the wrong branch (build_test), I changed it to main, but maybe it should be closed..

[melissawm]

@vsnupoudel gentle ping, do you have plans to update this PR?

[vsnupoudel]

@vsnupoudel gentle ping, do you have plans to update this PR?

Hi there,
Not trying to be rude, but it feels like there is a lot of red tape, just to update a few sentences and examples.
Rules look more like opinions than actual rules.
Having said that, this pull request can be ignored. I was just trying to address a confusion I personally felt while reading it myself.
Sincerely,
Bishnu