On Tue, Dec 5, 2017 at 10:44 PM, Nathaniel Smith <njs@pobox.com> wrote:
On Tue, Dec 5, 2017 at 5:32 PM, Ralf Gommers <ralf.gommers@gmail.com> wrote:
>
>
> On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <njs@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