updated and prettified magic doc strings

[ivanov]

after #1309, the docs stopped building (sorry about this I didn't know that the See Also was so strictly parsed), but the solution in #1338 made it so that the See Also linked to the relevant magic functions by their python name (see image below). I've added a comment to the See Also strings to make it explicit how such magics are called.

Along the way (since I was now building the docs) I prettified a lot of the ipython code examples with .. sourcecode :: ipython and corrected many other places where the ReST was off

There are probably many-many instances of such doc-only improvements which can be made all throughout IPython. It would be a good opportunity for someone with time on their hands to go through, spot places where small ReST changes would improve readability, and spend the time to iteratively improving and rebuilding the docs to verify these changes. Just putting it out there for the benefit of lurkers, or in case someone wants to refer to this PR to point out the kind of work that's a bit time consuming, but not impossibly hard. I just kept having to run make html in my ipython/docs directory - which luckily only takes a long time to build the docs the first time - after that, each run essentially only rebuilds the portions which were changed from the previous

[minrk]

This is nice, thanks. I'm always struggling with fully sphinxified docstrings vs light rst. Adding the sphinx markup makes the online docs prettier, but adds noise do the interactive view inside IPython.

And you are right - a sweeping pass to cleanup any/all docstrings and/or documentation is always a great way for new folks to contribute. Some of these docstrings are super old. Our documentation is still the biggest shortcoming in IPython, especially after the major reorganization in 0.11, which would love a matching effort on the docs.

[fperez]

This is great, @ivanov! Please do ping both the -dev and -user list with this one, as it's indeed a great example of places where new users can make contributions. I'll be sure to chime in as well :)

[minrk]

@fperez do we have official preferences for how sphinxified docstrings should be? I've typically avoided using .. sourcecode:: ipython in docstrings for interactive methods, because it is a detriment to their appearance in unrendered views (e.g. method?), and prevents a simple rest-renderer without Sphinx extensions from being able to draw them.

[fperez]

@minrk, I hadn't really thought much about it so far, but we might as well now. My gut tells me that we should draw the line at not requring sphinx itself to render docstrings well. Eventually I'm sure we'll end up having an optional docutils-based tool to parse docstrings for ?, that can produce basic HTML as well as a cleaned-up plaintext. I think having to rely on full-blown sphinx for that task is a bit over the top.

So perhaps a good guideline is: plain reST for docstrings, fancier sphinx extensions OK for the rest of the docs themselves. How does that sound?

[minrk]

So perhaps a good guideline is: plain reST for docstrings, fancier sphinx extensions OK for the rest of the docs themselves. How does that sound?

That seems sensible to me. What should we do about IPython snippets, then? Leave them as plain literal blocks, or try to make them identifiable somehow?

[fperez]

I think it's fine if they stay as plain literal blocks. They're meant to be small anyway, so the lack of a bit of visual polish isn't in my mind a huge deal, when weighed against the complexity that it would require to fix that up.

[ivanov]

ok, changed the .. sourcecode :: ipython bits back to literal blocks - and found a few other places that needed polish

[minrk]

Thanks!