Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Organize example notebooks #2537

Merged
merged 12 commits into from

6 participants

@ellisonbg
Owner

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
Owner

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
Owner

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
Owner

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
Owner
@ellisonbg
Owner

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
Owner

FYI this does not merge cleanly anymore.

@takluyver
Owner

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

@ellisonbg
Owner

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

@minrk
Owner

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
Owner

@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
Owner

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
Owner
@ellisonbg
Owner

@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
Owner

Seem good.

@Carreau
Owner

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

@ellisonbg
Owner
@Carreau
Owner

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

@ellisonbg
Owner

Rebased and ready to go.

@minrk
Owner

Merging now, thanks guys!

@minrk minrk merged commit 040d847 into ipython:master
@bfroehle

Thanks! This is great.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jan 19, 2013
  1. @ellisonbg
  2. @ellisonbg
  3. @ellisonbg
  4. @ellisonbg
  5. @ellisonbg
  6. @ellisonbg

    Adding Cell Magics notebook.

    ellisonbg authored
  7. @takluyver @ellisonbg
  8. @takluyver @ellisonbg
  9. @takluyver @ellisonbg
  10. @ellisonbg
  11. @ellisonbg

    Updating docs to reflect new examples.

    ellisonbg authored
    * Changed literalinclude paths to point to /examples.
    * Removed parallel options demo from parallel_demos.txt as it
      is now a notebook. Eventually we will find a way to integrate
      notebooks with the sphinx docs, but that is beyond the scope of
      this branch.
  12. @ellisonbg
Something went wrong with that request. Please try again.