[Numpy-discussion] NEP process update

[Jarrod Millman]

I was planning on looking at/working on the main doc generating system
and the main webpage (for numpy and scipy) soon (over the winter
break), but I didn't want to get too many things in the discussion
right now.  My immediate interest is getting agreement on the first
two items:

- A purpose and process NEP based on PEP 1 and a few other projects.
- A draft NEP template.

I am ambivalent about whether we need a separate repo.  My immediate
plan is start drafting text as a PR to numpy/doc/neps on Thursday
(assuming no major objections arise before then).  That way we can
discuss the NEP purpose/process and template docs, while I look into
the build system.  I was imaging doing something similar to what I did
for for networkx this summer:
  https://networkx.github.io/
The latest docs are autogenerated whenever a PR is merged into master:
  https://networkx.github.io/documentation/latest/

I will look into the scipy system as well and make sure we don't have
an explosion of systems.

Jarrod

On Tue, Dec 5, 2017 at 5:32 PM, Ralf Gommers <ralf.gommers at gmail.com> wrote:
>
>
> 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
>
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>