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