Did we hack our numpydoc at some point?

We certainly did. The merge with upstream is not so simple.

@jnothman This PR does it. And it's not so bad. There are two changes relative to numpydoc master in here. I would argue both are bugfixes (and have PRs to upstream)

This PR does it. And it's not so bad.

Sorry I didn't read properly. Would it be worth doing a diff of the HTML generated to make sure you've not missed any differences?

There are probably quite some differences, but I'll try to do a diff.

There is no table for the methods with links, and the attributes are now below the notes. The attributes should be documented like the methods now. I'm not sure where the method table went, I think that was my fault.

So this might indeed need a little bit more work.

This should be good now. The new version has the Attribute section next to the Methods section, instead next to the Parameters section. Otherwise the docs should be pretty much the same.

I don't think having attributes after References makes sense in our context, even if I get why Attributes and Methods logically fit together. Should we change numpydoc to make this configurable?

Also, I think we should rename numpy_ext to numpydoc?

happy to change numpy_ext to numpydoc, this way I thought the diff would be easier to read (though I guess a git mv should work).

Making the order of sections configurable would be nice indeed. It's not super obvious but doable.
I'm not sure what a good order would be though. Do you think methods after references makes sense?

The ordering should emphasise the "things you should know" or "things you
might not know were there" first. It's fine to have methods after
references, as methods are mostly common (with small variation). I'd also
like to find a way to put the gallery of auto_examples higher in the file,
but am not sure how that interacts with sphinx_gallery, and didn't find a
way to do it easily when I first introduced the gallery.

On 3 November 2016 at 08:28, Andreas Mueller notifications@github.com
wrote:

happy to change numpy_ext to numpydoc, this way I thought the diff would
be easier to read (though I guess a git mv should work).

Making the order of sections configurable would be nice indeed. It's not
super obvious but doable.
I'm not sure what a good order would be though. Do you think methods after
references makes sense?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#7355 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAEz69nPzLj3fSxCAnYwETuVl-wdCgL-ks5q6QCLgaJpZM4J3NUn
.

I think the key point, though, is that attributes are more important for a
description of our estimators than they are in numpy docs.

On 3 November 2016 at 12:03, Joel Nothman joel.nothman@gmail.com wrote:

The ordering should emphasise the "things you should know" or "things you
might not know were there" first. It's fine to have methods after
references, as methods are mostly common (with small variation). I'd also
like to find a way to put the gallery of auto_examples higher in the file,
but am not sure how that interacts with sphinx_gallery, and didn't find a
way to do it easily when I first introduced the gallery.

On 3 November 2016 at 08:28, Andreas Mueller notifications@github.com
wrote:

happy to change numpy_ext to numpydoc, this way I thought the diff would
be easier to read (though I guess a git mv should work).

Making the order of sections configurable would be nice indeed. It's not
super obvious but doable.
I'm not sure what a good order would be though. Do you think methods
after references makes sense?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#7355 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAEz69nPzLj3fSxCAnYwETuVl-wdCgL-ks5q6QCLgaJpZM4J3NUn
.

Feature request: Is it possible to move numpydoc to sklearn/externals? It will help in #7793.

yes, but we need numpy/numpydoc#77 first. Hurray for cross-project dependency chains!

We can do this now... :)))

I would like to see this happen. It holds up some other fixes. But I'd also rather see us depend on numpydoc as a pypi dependency rather than including the source. WDYT?

right now the circle build doesn't have the template mechanism for moving the attributes up. But otherwise it looks good. We can either wait for a numpydoc release (which seems imminent) or pip install the github version. Without this it's near impossible to fix doc build errors....

yeah, it's not really ;)

The thing is more that it helps get rid of all the issues in the website. Cherry picking to and fro from this branch is pretty annoying.

Numpydoc was just released, I'm triggering Circle so we can see what it looks like.

The files doc/sphinxext/README.txt and doc/sphinxext/LICENSE.txt should be deleted (I think).

@ogrisel done :)

This has drastically changed the attributes listing. See any class, e.g. http://scikit-learn.org/dev/modules/generated/sklearn.cluster.bicluster.SpectralBiclustering.html

Compare http://scikit-learn.org/0.19/modules/generated/sklearn.cluster.bicluster.SpectralBiclustering.html

Numpydoc changed Attributes from a Parameter List to a Member List.

@jnothman I though we were fine with that? I posted screenshots above.

I don't think it's unreadable, but yeah, it was better before. So we could revert, monkey patch, or fix in upstream and use a dev version to build the website?

A particularly bad case of attributes at http://scikit-learn.org/dev/modules/generated/sklearn.model_selection.GridSearchCV.html. See numpy/numpydoc#104. Perhaps we should consider reverting before we get bug reports about this, pending some fixes upstream that I hope I find time to make.

That's indeed pretty bad. I'm slightly against reverting because it makes error messages unreadable. But I guess readable docs is more important than readable doc-building error messages.