On 5 December 2017 at 17:32, Ralf Gommers <ralf.gomm...@gmail.com> wrote: > > > On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <n...@pobox.com> wrote: >> >> On Tue, Dec 5, 2017 at 4:12 PM, Ralf Gommers <ralf.gomm...@gmail.com> >> wrote: >> > On Wed, Dec 6, 2017 at 12:31 PM, Jarrod Millman <mill...@berkeley.edu> >> > wrote: >> >> Assuming that sounds good, my tentative next steps are: >> >> >> >> - I'll draft a purpose and process NEP based on PEP 1 and a few other >> >> projects. >> >> - I'll also create a draft NEP template. >> > >> > >> > sounds good >> > >> >> - I'll move the NEPs into their own repo (something like numpy/neps), >> > >> > This doesn't sound ideal to me - NEPs are important pieces of >> > documentation, >> > so I'd rather keep them included in the main docs. >> > >> >> and set up an automated system (RTD or Github pages) to >> >> render and publish them with some useful index. >> > >> > >> > If you could copy over the scipy method to rebuild the docs on each >> > merge >> > into master, that would achieve the same purpose. Compare >> > https://docs.scipy.org/doc/numpy-dev/reference/ (outdated) vs >> > https://docs.scipy.org/doc/scipy-dev/reference/ (redirects to >> > http://scipy.github.io/devdocs/, always up-to-date). >> >> Yeah, we were debating back and forth on this -- I can see arguments >> either way. The reasons we were leaning towards splitting them out >> are: >> >> - it would be great to make our regular docs auto-generated, but we >> didn't necessarily want to block this on that > > > This is easy, it's just copying a trick from SciPy. (and that's work that > anyway needs doing at some point, sooner rather than later) >
I can probably help out with that. It's very straightforward once you've done it a couple of time. I'm also a strong believer in automating as much as possible. >> - part of the idea is to auto-generate the NEP index out of the >> metadata inside each NEP file, which is going to involve writing some >> code and integrating it into the NEP build. This seems easier if we >> don't have to integrate it into the overall doc build process too, >> which already has a lot of custom code. > > > This is easy too, if you have your script to auto-generate an index file, > it's just calling that file from within `doc/Makefile`. > >> - 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. > > It's probably less effort even to keep them where they are rather than > creating a separate repo, setting up RTD for it, and linking to that from > our main docs. > > Ralf > > > _______________________________________________ > 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
