updated and prettified magic doc strings #1385

Merged
merged 2 commits into from Feb 19, 2012

Projects

None yet

3 participants

@ivanov
IPython member

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.

Imgur

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

Pretty

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
IPython member

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
IPython member

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
IPython member

@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
IPython member

@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
IPython member

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
IPython member

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 ivanov further fixes to magic docstrings
as discussed in PR #1385, "plain reST for docstrings, fancier sphinx
extensions OK for the rest of the docs themselves."

So I've removed ..  sourcecode :: ipython bits with just plain literal
blocks
bd21875
@ivanov
IPython member

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

@minrk
IPython member

Thanks!

@minrk minrk merged commit d3fe9b7 into ipython:master Feb 19, 2012
@mattvonrocketstein mattvonrocketstein pushed a commit to mattvonrocketstein/ipython that referenced this pull request Nov 3, 2014
@ivanov ivanov further fixes to magic docstrings
as discussed in PR #1385, "plain reST for docstrings, fancier sphinx
extensions OK for the rest of the docs themselves."

So I've removed ..  sourcecode :: ipython bits with just plain literal
blocks
f2444db
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment