DOC: add a section on NumPy's module structure to the refguide #25674
Conversation
|
Thanks for this Ralf! The |
| @@ -23,7 +23,6 @@ indentation. | |||
| routines.bitwise | |||
| routines.char | |||
| routines.strings | |||
| routines.ctypeslib | |||
There was a problem hiding this comment.
Slightly confused why these are removed here.
There was a problem hiding this comment.
This listing is by design an opinionated way of splitting up NumPy's main functionality into separate topics. Its coverage is incomplete for what's in the main namespace, and many more niche/legacy/deprecated topics and namespaces are not covered. So these edits make the listed topics more sensible. It's only a first cut with the most obvious changes that (to me) are really no-no's to list here. It does require further improvements (example: there are two string topics, and the one with the more general name points to numpy.char not numpy.strings).
As for the specific entries removed here:
ctypeslib: not relevant for 99.x% of users, so way too niche to list here - and now covered in the new module structure pagenumpy.lib: that's simply not a coherent topic at all, so an entry for it does not make senseroutines.matlib: only contains a few functions and, more importantly, we're going to deprecatematrixusage and don't want any new code using it, so exposing this topic is not right anymoretesting.overrides: way too niche to list here, folded into the regularnumpy.testingpage
Note that this is the second iteration of editing this section (after gh-25650), and there'll be at least one more. Probably after exercising the .. legacy:: directive on a bunch of stuff.
There was a problem hiding this comment.
OK, that makes sense. Resolved for me, but leaving it open for possible other reviewers, just because it is hard to understand why this was done in isolation.
There was a problem hiding this comment.
I have now added a comment above this toctree for context, that should hopefully help keep things understandable and in better shape.
| @@ -23,7 +23,6 @@ indentation. | |||
| routines.bitwise | |||
| routines.char | |||
| routines.strings | |||
| routines.ctypeslib | |||
There was a problem hiding this comment.
OK, that makes sense. Resolved for me, but leaving it open for possible other reviewers, just because it is hard to understand why this was done in isolation.
Also add some context to the "Routines and objects by topic" listing, since that was helpful during PR review, and clean that up some more. [skip cirrus] [skip azp]
edb9563 to
a33fc02
Compare
|
This is good to go now. |
|
Thanks @rgommers |
This addresses the main remaining item of NEP 52 - Python API cleanup for NumPy 2.0.
Most modules now have a reasonable page to land on with a full function/object listing of what's in their namespace. The exceptions are:
numpynamespace; that has always been done per topic - it'd be quite nice to also have a single page with everything in the namespace, but that's a fight with Sphinx that is not so easy to win. So leaving that for another time.numpy.random: missing a function listing and the docs need more cleanup; that's a long-standing issue so also considering that out of scope here.numpy.dtypes: this file was left out of a recent PR, @ngoldbaum said he would fix that this week.Also incorporate a number of other fixes as I bumped into issues (Sphinx warnings, use of private namespaces in examples, missing page headers, etc.).