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
documentation. A separate repo has downsides though (discoverability etc.), we also keep our dev docs within the numpy repo and you can make exactly
same argument about those as about NEPs. So I'd still suggest keeping
serve as the 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