[Numpy-discussion] NEP process update

Ralf Gommers ralf.gommers at gmail.com
Tue Dec 5 20:32:01 EST 2017


On Wed, Dec 6, 2017 at 1:49 PM, Nathaniel Smith <njs at pobox.com> wrote:

> On Tue, Dec 5, 2017 at 4:12 PM, Ralf Gommers <ralf.gommers at gmail.com>
> wrote:
> > On Wed, Dec 6, 2017 at 12:31 PM, Jarrod Millman <millman at 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)

- 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20171206/c00ef12c/attachment-0001.html>


More information about the NumPy-Discussion mailing list