On Wed, Dec 6, 2017 at 5:39 PM, <josef.p...@gmail.com> wrote: > > > 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 > > indeed. possibly governance as well.
>> >> 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. > These have recently been moved to https://numpydoc.readthedocs.io/en/latest/format.html Ralf > 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 > >
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
