On Thu, Oct 14, 2021 at 7:22 PM Ralf Gommers <ralf.gommers@gmail.com> wrote:


On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard <kevin.k.sheppard@gmail.com> wrote:
I think the issue in random specifically is that a raw list of available functions does not provide suitable guidance for someone looking for random variate generating function.  This is because the module-level API is mostly dominated by methods of the singleton RandomState instance.  Best practice going forward is to use the methods of a Generator instance, most likely provided by default_rng(). A simple API-list will not be able to provide this guidance. 

The list can be annotated with headings and one-line or one-paragraph descriptions, something like:

```
## Generator interface

This is the recommended interface ... <etc - list methods too>

## Interface for unit testing and legacy code

<explain purpose, then list all routines>
```

The complaint is very much valid here, I have made the same one before. The way the page currently is written makes little sense - it addresses a user transitioning from the old to the new interface, or explicitly comparing the two for some reason. To a user just looking for information on NumPy today, that's more confusing than helpful.

The page also talks about "The new interface", "What's new and different", "Some long-overdue API cleanup", and "Since Numpy version 1.17.0" - that all belongs in a NEP, and not in the API reference docs.

Cheers,
Ralf



I don't think the doc style there is ideal.  I would still say that a relatively naive dump of `np.random` (something that would be everything in [v for v in dir(np.random) if not v.startswith("_")] would not lead to an idea set of docs because most of the "obvious" functions are methods of the legacy RandomState.  A good set would need something like (excluding headers)

default_rng
Generator
Generator.random
Generator.integers
...

<much lower, or IMO better in a a sperate page>
Legacy Methods
==============
<short explainer> 
np.random.random_sample
np.random.randint
RandmState
...
 
IMO many (likely most) methods exposed in np.random should not be on the default landing page for np.random.

Best,
Kevin



FFT has a very simple API and so a simple list make sense.  Similarly, np.random before the generation was revamped, which is hy the old-style was adequate for <=1.16, but not for >=1.17

Kevin


On Thu, Oct 14, 2021 at 6:09 PM Paul M. <pmmagic@gmail.com> wrote:
Hi Melissa,

I think that's the right approach.  Looking through the current docs, I think the page on the FFT module is exemplary in this regard:


It lists all the available functions (with links to details), and then has a section on "Background Information", "Implementation Details", etc.  It's easy to get a quick overview of what the available functions are, and then ease into the background info in terms of how it works.

Cheers,
Paul


On Thu, Oct 14, 2021 at 12:44 PM Melissa Mendonça <melissawm@gmail.com> wrote:
Hi Paul,

Do you think having a page with the flat list of routines back, in addition to the explanations, would solve this?

- Melissa

On Thu, Oct 14, 2021 at 1:34 PM Paul M. <pmmagic@gmail.com> wrote:
Hi All,

The documentation of Numpy's submodules  used to have a fairly standard structure as shown here in the 1.16 documentation:


Now the same page in the API documentation looks like this:


While I appreciate the expository text in the new documentation about how the generators work, this new version is much less useful as a reference to the API.  It seems like it might fit better in the user manual rather than the API reference. 

From my perspective it seems like the new version of the documentation is harder to navigate in terms of finding information quickly (more scrolling, harder to get a bird's eye view of functions in various submodules, etc). 

Has anyone else had a similar reaction to the changes? I teach a couple of courses in scientific computing and bioinformatics and my students seem to also struggle to get a sense of what the different modules offer based on the new version of the documentation. For now, I'm referring them to the old (1.70) reference manuals as a better way to get acquainted with the libraries.

Cheers,
Paul Magwene
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-leave@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: melissawm@gmail.com
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-leave@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: pmmagic@gmail.com
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-leave@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: kevin.k.sheppard@gmail.com
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-leave@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: ralf.gommers@googlemail.com
_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-leave@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: kevin.k.sheppard@gmail.com