On Thu, Oct 14, 2021 at 7:19 PM Kevin Sheppard <[email protected]> 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 > 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. <[email protected]> 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: >> >> https://numpy.org/doc/stable/reference/routines.fft.html >> >> 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 <[email protected]> >> 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. <[email protected]> wrote: >>> >>>> Hi All, >>>> >>>> The documentation of Numpy's submodules used to have a fairly standard >>>> structure as shown here in the 1.16 documentation: >>>> >>>> >>>> https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html >>>> >>>> Now the same page in the API documentation looks like this: >>>> >>>> https://numpy.org/doc/stable/reference/random/index.html >>>> >>>> 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 -- [email protected] >>>> To unsubscribe send an email to [email protected] >>>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>>> Member address: [email protected] >>>> >>> _______________________________________________ >>> NumPy-Discussion mailing list -- [email protected] >>> To unsubscribe send an email to [email protected] >>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>> Member address: [email protected] >>> >> _______________________________________________ >> NumPy-Discussion mailing list -- [email protected] >> To unsubscribe send an email to [email protected] >> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >> Member address: [email protected] >> > _______________________________________________ > NumPy-Discussion mailing list -- [email protected] > To unsubscribe send an email to [email protected] > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: [email protected] >
_______________________________________________ NumPy-Discussion mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: [email protected]
