Organize example notebooks

[ellisonbg]

This branch does two things:

• I have moved our examples directory out of the docs dir, to make it top level and easier to find.
• I have refactored and rewritten the Notebook examples.

Questions:

• Some of the notebook examples still have a very tutorial feel that doesn't really match the idea of "examples". But they still really do show examples of the notebook. I am not sure how we want to organize this type of material - I still think the current org is lacking. Would love ideas on how to handle it.

[Carreau]

We'll just need to update nbviewer front page when this is merged, as one of the example is used on the front page and is one of the notebook that have the most views.

[Carreau]

BTW, totally out of subject, but while I think of it.
Why not use hash(full notebook path on system) for kernel UUID?

It does not change after server restart, there is a relatively low risk of collision.

[fperez]

I think we should discuss further the moving of examples to the top directory... I'm currently -1 on that idea, b/c I think what we need to do is restructure our doc build itself to include all notebooks as part of the static HTML docs in the end. I'm thrilled to see the reorganization, but the one-directory-up I'm not convinced of. If we do that, pulling the notebooks into the sphinx builds will be pretty awkward.

[minrk]

And note that several of the examples are already included in the sphinx
docs via 'literalinclude'. I know the mcpricer section of the docs was
broken when someone notebookized that example, discarding the code that was
included in the sphinx docs. So we do need to be more careful about this
than we have been in the past.

-MinRK

On Wed, Oct 31, 2012 at 3:47 PM, Fernando Perez notifications@github.comwrote:

I think we should discuss further the moving of examples to the top
directory... I'm currently -1 on that idea, b/c I think what we need to do
is restructure our doc build itself to include all notebooks as part of the
static HTML docs in the end. I'm thrilled to see the reorganization, but
the one-directory-up I'm not convinced of. If we do that, pulling the
notebooks into the sphinx builds will be pretty awkward.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2537#issuecomment-9959343.

[ellisonbg]

These are all great points - but I don't think the solution is to move examples back into /docs:

• The current realization of the docs directory is that it is really the gory internals of the sphinx documentation build. It is not a place that is designed for users to go and start out. If we want to point new users at these notebooks it should be in a user friendly location, not burried in our sphinx docs.
• The material in examples is a horrible mix of random things, raging from standalone .py examples, domain specific examples (Monte-Carlo options pricing), full blown tutorial notebooks, etc. I don't think these things all below together. We need some fresh ideas on 1) what types of code related learning materials we do want 2) how those should be organized and 3) where they should be. This is complicated to the existence of the ipython/talks and ipython/ipython-in-depth repos that have additional tutorlal style information.
• If we do want to embed notebooks in sphinx, there is not any problem will pulling that content from outside the docs directories (from a top-level examples directory or somewhere else).

[Carreau]

FYI this does not merge cleanly anymore.

[takluyver]

Are we closer to coming to a conclusion about this? #2627 is kind of in limbo until we decide on this one.

[ellisonbg]

OK I think this is ready to merge. @mink and @takluyver do you want to have a quick look before this goes in?

[minrk]

Quick skim looks fine - I would do an HTML docs build, and make sure no literalincludes are missing. But if that checks out, I'm okay to merge.

[Carreau]

@ellisonbg Maybe you will want to "validate" the notebook and/or write one to present the slideshow mode.
But this can be done later.

[Carreau]

Side note, please let me merge, or think in updating the nbviewer front page that point to notebook docs on git master and which would break otherwise.

[ellisonbg]

@minrk I haven't been able to build the HTML docs on my Mac for a really
long time. But I just built the HTMl docs on Linux. I tried looking
through the warnings vomit and couldn't find anything obvious complaining
about the included files. Our docs need a doc.

On Mon, Jan 14, 2013 at 12:52 PM, Bussonnier Matthias <
notifications@github.com> wrote:

@ellisonbg https://github.com/ellisonbg Maybe you will want to
"validate" the notebook and/or write one to present the slideshow mode.
But this can be done later.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2537#issuecomment-12239081.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[ellisonbg]

@Carreau what is the best way to coordinate with nbviewer? How about this: I won't merge this branch now. You can update nbviewer and when it is ready you can merge this and deploy nbviewer.

[Carreau]

Seem good.

[Carreau]

examples/lib/BackgroundJobs.ipynb is a V2 notebook
examples/parallel/rmt/rmt.ipynb is V2
examples/tests/heartbeat/gilsleep.ipynb is V2

[ellisonbg]

OK I just pushed the v3 versions.

On Tue, Jan 15, 2013 at 12:01 PM, Bussonnier Matthias <
notifications@github.com> wrote:

examples/lib/BackgroundJobs.ipynb is a V2 notebook
examples/parallel/rmt/rmt.ipynb is V2
examples/tests/heartbeat/gilsleep.ipynb is V2

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2537#issuecomment-12286165.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[Carreau]

With the huge number of merged PR in the last 2 days this one got a conflict.
Could you rebase it ?

[ellisonbg]

Rebased and ready to go.

[minrk]

Merging now, thanks guys!

[bfroehle]

Thanks! This is great.