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.
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. <pmma...@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: > > 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 <meliss...@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. <pmma...@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: >>> >>> 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 -- numpy-discussion@python.org >>> To unsubscribe send an email to numpy-discussion-le...@python.org >>> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >>> Member address: meliss...@gmail.com >>> >> _______________________________________________ >> NumPy-Discussion mailing list -- numpy-discussion@python.org >> To unsubscribe send an email to numpy-discussion-le...@python.org >> https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ >> Member address: pmma...@gmail.com >> > _______________________________________________ > NumPy-Discussion mailing list -- numpy-discussion@python.org > To unsubscribe send an email to numpy-discussion-le...@python.org > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: kevin.k.shepp...@gmail.com >
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-le...@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: arch...@mail-archive.com
