On Tue, Dec 5, 2017 at 10:44 PM, Nathaniel Smith <n...@pobox.com> wrote:
> On Tue, Dec 5, 2017 at 5:32 PM, Ralf Gommers <ralf.gomm...@gmail.com> > wrote: > > > > > > On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <n...@pobox.com> wrote: > >> - NEPs are really part of the development process, not an output for > >> end-users -- they're certainly useful to have available as a > >> reference, but if we're asking end-users to look at them on a regular > >> basis then I think we've messed up and should improve our actual > >> documentation :-) > >> - NEPs have a different natural life-cycle than numpy itself. Right > >> now, if I google "numpy neps", the first hit is the 1.13 version of > >> the NEPs, and the third hit is someone else's copy of the 1.9 version > >> of the NEPs. What you actually want in every case is the latest > >> development version of the NEPs, and the idea of "numpy 1.13 NEPs" > >> doesn't even make sense, because NEPs are not describing a specific > >> numpy release. > > > > > > The last two points are good arguments, I agree that they shouldn't > serve as > > documentation. A separate repo has downsides though (discoverability > etc.), > > we also keep our dev docs within the numpy repo and you can make exactly > the > > same argument about those as about NEPs. So I'd still suggest keeping > them > > where they are. Or otherwise move all development related docs. > > Are these the dev docs you're thinking of? > https://docs.scipy.org/doc/numpy-dev/dev/index.html > > Regarding discoverability, right now it looks like the only way to > find the latest NEPs on google is by searching for something like > "numpy-dev neps", which is pretty obscure. (It took me 4 tries to find > something that worked. "numpy neps" seemed to work, but actually sent > me to an out-of-date snapshot.) In Python, the PEP web pages are > rebuilt on something like a 6 hour timer, and it's actually super > annoying, because it means that when someone posts to the list like > "hey, I just pushed a new version, tell me what you think", everyone > goes and finds the old stale version, sometimes people start > critiquing it, ... it's just confusing all around. So I do think we > want to make sure there's some simple way to find them, and that it > leads to the latest version, not a stale build or an old snapshot. > > Moving NEPs + development docs to their own dedicated repo would > resolve this and seems like a plausible option to me. We could > probably do better than we are now with the regular docs too. Though > the experience with PEPs does make me a bit nervous about having > versioned snapshots of the NEPs in all our old versioned manuals > (which have tons of google-juice). > maybe I have a different google, but the first search result for me for "numpy nep" is https://docs.scipy.org/doc/numpy-dev/neps/index.html developer guides are on top here https://docs.scipy.org/doc/ using the link for "Complete Numpy Manual" on that page has dev docs and neps listed. But I don't see "numpy doc standard" which I usually need to google and the search leads to github page for it. Searching for specific items leads often to older versions in google and needs manual interventions, e.g. edit the version number in link Aside: My main occasion for reading Peps (besides quoting ZEN) is to follow the links in the python what's new pages, e.g. https://docs.python.org/3/whatsnew/3.6.html Josef > > -n > > -- > Nathaniel J. Smith -- https://vorpus.org > _______________________________________________ > NumPy-Discussion mailing list > NumPy-Discussion@python.org > https://mail.python.org/mailman/listinfo/numpy-discussion >
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
