Maccarthy, Jonathan K | 25 Jan 17:56 2012

View rendered reStructuredText (Sphinx) docstrings in iPython?

Hello,

Does anyone know if it's possible to have iPython render reStructuredText (i.e. Sphinx) docstrings when
you type 'help foo', or 'foo?'  ?  I'm finding that many projects are moving to Sphinx documentation, which
makes their docstrings harder to read on the fly (unpythonic?).  <rant> Needing a browser to view the docs
seems to miss the point of docstrings. </rant>  Does iPython have this functionality somewhere?  If not,
perhaps any devs could suggest where in the iPython source it would go (if this is even feasible)?

Thanks in advance,
Jon
Thomas Kluyver | 26 Jan 17:06 2012
Picon

Re: View rendered reStructuredText (Sphinx) docstrings in iPython?

Hi Jon,

So, there's different bits of IPython. In the terminal, we're quite limited in what we can do - most modern terminals let us change the colour of text, or make it slightly bold. It would be possible to do some rendering of reST here (e.g. convert *emphasis* to bold text), but it's very limited; especially with links (which I think are the most disruptive thing for reading raw reST), you can't hide the URL.

In the Qt console and now the HTML notebook, the situation is much better - you could render the reST to HTML for the frontend to display.

A command like zip? is translated to get_ipython().magic(u'pinfo zip') , which calls the magic_pinfo function:
https://github.com/ipython/ipython/blob/master/IPython/core/magic.py#L541

That in turn calls shell.inspect.pinfo, which is here:
https://github.com/ipython/ipython/blob/master/IPython/core/oinspect.py#L435

I think probably the best approach would be to make an extension ( http://ipython.org/ipython-doc/stable/config/extensions/index.html ), which would subclass Inspector, overriding the pinfo method with one that produced an HTML result to send to the frontend.

Best wishes,
Thomas

On 25 January 2012 16:56, Maccarthy, Jonathan K <jkmacc <at> lanl.gov> wrote:
Hello,

Does anyone know if it's possible to have iPython render reStructuredText (i.e. Sphinx) docstrings when you type 'help foo', or 'foo?'  ?  I'm finding that many projects are moving to Sphinx documentation, which makes their docstrings harder to read on the fly (unpythonic?).  <rant> Needing a browser to view the docs seems to miss the point of docstrings. </rant>  Does iPython have this functionality somewhere?  If not, perhaps any devs could suggest where in the iPython source it would go (if this is even feasible)?

Thanks in advance,
Jon
_______________________________________________
IPython-User mailing list
IPython-User <at> scipy.org
http://mail.scipy.org/mailman/listinfo/ipython-user

_______________________________________________
IPython-User mailing list
IPython-User <at> scipy.org
http://mail.scipy.org/mailman/listinfo/ipython-user
Fernando Perez | 26 Jan 21:35 2012
Picon

Re: View rendered reStructuredText (Sphinx) docstrings in iPython?

On Thu, Jan 26, 2012 at 8:06 AM, Thomas Kluyver <takowl <at> gmail.com> wrote:
> I think probably the best approach would be to make an extension (
> http://ipython.org/ipython-doc/stable/config/extensions/index.html ), which
> would subclass Inspector, overriding the pinfo method with one that produced
> an HTML result to send to the frontend.

Note that we already have support for sending *both* html and
plaintext to the pager, you can see it by opening a qtconsole and then
opening a text console with

ipython console --existing

Then type %guiref in both.  The qt one will show the html formatted
help, while the text console will show the basic text.

So the ideal path would be an extension that simply uses docutils to
emit plaintext from the docstrings stripped of reST markup as well as
html, and sends both outputs.  This way, the clients that can show
html will use it and the text terminal will  get more readable
plaintext.

This would need to be optional b/c we don't want to make docutils a
mandatory requirement, but if it's included in ipython, then users who
want it can just enable it in their default profile.

Cheers,

f
Maccarthy, Jonathan K | 26 Jan 21:46 2012

Re: View rendered reStructuredText (Sphinx) docstrings in iPython?


> So the ideal path would be an extension that simply uses docutils to
> emit plaintext from the docstrings stripped of reST markup as well as
> html, and sends both outputs.  This way, the clients that can show
> html will use it and the text terminal will  get more readable
> plaintext.
> 

This seems like a more tractable path for someone who's not mucked around in the ipython source before. 
Something like  "%load_ext render_reST" seems like what I'd imagined.  Cleaning up a subset of reST would
be a big help, I think.  

Thanks to you both!

-J

> This would need to be optional b/c we don't want to make docutils a
> mandatory requirement, but if it's included in ipython, then users who
> want it can just enable it in their default profile.
> 
> Cheers,
> 
> f
klo uo | 27 Jan 22:46 2012
Picon

Re: View rendered reStructuredText (Sphinx) docstrings in iPython?

I was curious similarly: in Qt console "%guiref" displays nice rendered text with headers, code (/pre) formating, and was wondering if most common packages like numpy and scipy (and others) can be presented on help pager formatted. Like actual LaTeX formulas be rendered on help pager, instead literal LaTeX syntax?

_______________________________________________
IPython-User mailing list
IPython-User <at> scipy.org
http://mail.scipy.org/mailman/listinfo/ipython-user
Fernando Perez | 28 Jan 00:12 2012
Picon

Re: View rendered reStructuredText (Sphinx) docstrings in iPython?

On Fri, Jan 27, 2012 at 1:46 PM, klo uo <klonuo <at> gmail.com> wrote:
> I was curious similarly: in Qt console "%guiref" displays nice rendered text
> with headers, code (/pre) formating, and was wondering if most common
> packages like numpy and scipy (and others) can be presented on help pager
> formatted. Like actual LaTeX formulas be rendered on help pager, instead
> literal LaTeX syntax?

In the qt console, no, b/c we don't have a tex renderer available
there.  But on the notebook, it could be made to work since we can
hook into the MathJax renderer we're already using.

Cheers,

f

Gmane