ipython/ipython — pull request #5337 by ellisonbg (2014-03-12 21:29:05+00:00)
Title: Examples reorganization

This PR reorganizes the top-level examples directory:

The main goal is to slowly evolve this directory into the main place for notebook based documentation for IPython. This includes narrative docs (which we are calling "Tutorials") and Examples.

The best way to review this PR is probably to look at it on nbviewer:

http://nbviewer.ipython.org/github/ellisonbg/ipython/tree/examples-reorg/examples/

* Top-level directories that organize the material *conceptually*. In some cases this corresponds to actual IPython subpackages, but that is not the point.
* Each top-level dir has a `Tutorials` and `Examples` sub-dirs.
* Existing content is mostly just moved into place, with a few minor edits.
* Content that is clearly out-of-date, stale, not relevant has been removed.

There is still a lot left to do in subsequent PRs:

* Create `Index.ipynb` files to better organize the material for the reader.
* Convert `.py` examples to notebooks where it makes sense.
* Add cross refs between notebooks.
* Transition our Sphinx docs to this tree, in many cases, just rewriting from scratch.

The only other thing I would like to do in this PR is make decisions about removing more stale examples. Here is a list of ones that I think are candidates for removal:

Do we still recommend people to embed using this class API?

* `Embedding/Examples/embed_class_long.py`
* `Embedding/Examples/embed_class_short.py`

Progress bars are not in widgets, do we still want the old Progress Bars examples?

* `Notebook/Examples/Progress Bars.ipynb`

From `Parallel/Examples`:

* `pi`: this example requires downloading massive amounts of data-not really something a user would ever run. It is also sort of silly.
* `map.py`: really trivial, this material would be covered by any narrative docs.
* `multiengine1.ipy`: a badly written mini-tutorial with no narrative.
* `multiengine2.py`: trivial, this material would be covered by any narrative docs.
* `multienginemap.py`: trivial, this material would be covered by any narrative docs.
* `task1.ipynb`: same
* `task2.py`: same
* `taskmap.ipynb`: same

What do we do with the `tests` directories. This stuff is not really examples or docs, they are tests that we have to run by hand. Is there a better place for them?