DOC: update numpydoc to current master (commit 223df02530)

[jorisvandenbossche]

This PR updates our local copy of numpydoc to latest upstream version (I just fully copied over that version, only left out setup.py and manifest.in). This would be a solution to the numpydoc part of issue #5221.

The intent would then be, from now on, to not touch this code, apart of pulling an updated version from numpydoc upstream from time to time. If we want to make a change, also send it upstreams to not let the two versions diverge.

Other options to solve this issue would be to just add numpydoc as a requirement for the doc building and removing out local option, or to add it as a git submodule. I am slightly in favor of removing our local copy, but I understood from previous comments it would be better to not have more build dependencies (and it would also tie us to a specific version).

I did build the docs with this and all seems OK. From looking at the history, I think only py3compat changes are done to these files after the initial import from Wes (@jtratner, @cpcloud you are the ones who touched these files, do you remember if you did something else than py3compat issues?)

[metakermit]

Hm... It's never-ending :/

numpy/numpydoc#8

The tests in numpydoc pass on Python 2, but with a couple of deprecation warnings and quite a few more when the -3 flag is passed:

python -3 -m unittest discover numpydoc/tests

[jorisvandenbossche]

@jreback @y-p What do you think about this?

Options are:

1. Periodically updating our local copy of numpydoc, and further not touching it (this PR does this)
2. numpydoc as external dependency to build the docs and remove this entirely from the source
3. add it as a gitmodule (this is what numpy and scipy do), but @jtratner had some objections about this.

[jreback]

👍 for removing deps....

@jtratner what was your objection?

[ghost]

I like 1. stay sync'ed but don't allow external changes to break our build arbitrarily.
numpydoc is probably not moving that fast anyway.

[jorisvandenbossche]

I personally have a slight preference for option 2, but I perfectly understand the reasoning for option 1. Then, we only must have the discipline to not make changes to it (although most changes in the past were for py2/3 compat, and I hope that won't be necessary again the coming years)

So if it's 1, this can be merged.

[ghost]

I wouldn't say we can't change things if we need to, we should make an honest attempt
at merging upstream first IMO, is all.

afaic, merge away.

[jorisvandenbossche]

Off course, if need be, then it is. But eg the py3 compat changes were also done upstream, so that was a little bit of duplication of effort.