On 5 December 2017 at 17:32, Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <njs@pobox.com> wrote:
On Tue, Dec 5, 2017 at 4:12 PM, Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Wed, Dec 6, 2017 at 12:31 PM, Jarrod Millman <millman@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