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)

- 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