Magic examples

[takluyver]

This combines and cleans up some of the documentation pull requests from Scipy India. So far, #218, #226 and #223 are included (%history, %pwd and %cd, respectively).

[minrk]

Great, thanks for sorting through these.

A note:
Even though there may only be one element in the list, the sections should still be called 'Examples'. The reason is that the autodoc reST sections are a whitelist, and sections not in that list are omitted entirely from the sphinx docs. 'Example' isn't in the list, but 'Examples' is.

You can check the output of your commits in the generated page: docs/build/html/api/generated/IPython.core.magic.html.

[fperez]

And additionally, the :: markers aren't needed. Otherwise looks good, thanks a lot for the work on all of the India stuff!

With those minor tweaks, go for the merge!

[takluyver]

OK, I've changed it to "Examples", and checked the output. Fernando, if I don't have the :: marker, it seems that it runs lines together into one. Is there a better way round that? I've left :: in for now.

I'm just going to see if there's any more pull requests that I should integrate here.

[minrk]

Great, thanks. It's running the lines into one because if it's not escaped as a literal block, so it's treating the two lines as a single paragraph.

Fernando, the :: is indeed necessary if you want it to be a literal block in the sphinx docs. Is sphinx supposed to be able to escape the Examples section into .. sourcecode: ipython? Because that would be very nice, but certainly is not what happens.

[takluyver]

Added #229 - pdef and colors.

[minrk]

One more note: You will want to decorate many of the methods you edit with @testdec.skip_doctest if the example output won't be reproducible by the doctesting (e.g. pwd, hist -n). iptest -v IPython.core.magic to check.

[takluyver]

Added #224 - %cpaste.

[takluyver]

Right, I think I'm done for now. How does this all look?

[minrk]

Looks great to me, I say go ahead and merge.

[fperez]

Thanks, guys! I guess I was thinking of pure python example blocks, where sphinx will (if I recall correctly) automatically make blocks.

In some cases, one can write a little sentence before the example explaining what it does, and just finish the sentence with the double ::. That makes it stand out less. But if there's no lead-in text, I guess it is indeed necessary to have the bare ::, sorry for the noise.