Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Magic examples #272

Merged
8 commits merged into from Feb 15, 2011

Conversation

Projects
None yet
8 participants
Owner

takluyver commented Feb 14, 2011

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).

08saikiranreddy and others added some commits Feb 14, 2011

Wrote examples for %cdmagic
Work done as a team by:
Anuradha Beetoju
Adish
Naveen
Shravan
Wrote example for %history
Work done as a team by:
-Srinivas Vinay A L
-Vishnu S G
Owner

minrk commented Feb 15, 2011

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.

Owner

fperez commented Feb 15, 2011

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!

Owner

takluyver commented Feb 15, 2011

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.

vsowjanya added some commits Feb 15, 2011

Wrote an example for 'pdef'
    Work done as a team by:
       -- V Sowjanya <hai.sowjanya@gmail.com>
       -- N Rajender Reddy <raj.rajender007@gmail.com>
       -- R Srikanth <sri.rajan143@gmail.com>
Wrote example for 'colors' command
Work done as a team by:
-- V Sowjanya <hai.sowjanya@gmail.com>
-- N Rajender Reddy <raj.rajender007@gmail.com>
-- R Srikanth <sri.rajan143@gmail.com>
Owner

minrk commented Feb 15, 2011

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.

Owner

takluyver commented Feb 15, 2011

Added #229 - pdef and colors.

Owner

minrk commented Feb 15, 2011

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.

Owner

takluyver commented Feb 15, 2011

Added #224 - %cpaste.

Owner

takluyver commented Feb 15, 2011

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

Owner

minrk commented Feb 15, 2011

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

Owner

fperez commented Feb 16, 2011

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.

This issue was closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment