Docs reorganization

[mrocklin]

I've been walking through the documentation and had a few notes. I'd be happy to make these changes but wanted to check in before I submitted anything.

The separation between single machine and distributed learning seems odd to me. Many of the topics listed in single machine (grid search, pipelining, possibly even incremental learning) are still relevant when on a cluster.

I might instead flatten the TOC to just remove the single-machine/distributed distinction, and give all of the subsections their own home. This might flatten the TOC to something like the following:

1. Pipelines
2. Hyper-parameter search
3. Incremental learning
4. Generalized Linear Models
5. Joblib
6. XGBoost
7. Clustering
8. Examples
9. API

I've also found it pleasant recently to start sections with the API relevant for that section. Futures docs for an example. This gives a quick list at the beginning of each section on the API relevant for that section. Those functions still link to the main API doc page.

Any thoughts or objections to this reorganization @TomAugspurger ?

[TomAugspurger]

The separation between single machine and distributed learning seems odd to me.

Agreed. I'm not sure why I found that distinction so relevant a few months ago.

Your proposed TOC sounds reasonable. For now, I think Pipelines would make a good home for things in preprocessing/.

I've also found it pleasant recently to start sections with the API relevant for that section.

That could get a bit boring for scikit-learn style estimators, since it'll (almost) always be.fit, .transform, etc :) Perhaps I'm misunderstanding though.

[TomAugspurger]

And if you're busy, I'll have time to work on this later today or tomorrow, as I wait around for pandas release things to finish.

[mrocklin]

That could get a bit boring for scikit-learn style estimators, since it'll (almost) always be.fit, .transform, etc :) Perhaps I'm misunderstanding though.

Yeah, to be clear I'm saying that we just add the .. autosummary: line at the top of each relevant section. When you go to the Generalized Linear Models section you see LinearRegression, LogisticRegression, PoissonRegression, _GLM at the top of the section. If you care to you can click on those to be taken to the full API docs on another page.