[IPython-User] Pretty rendering of docstrings

Matthias BUSSONNIER bussonniermatthias@gmail....
Thu Jan 24 02:06:36 CST 2013


Hi Gökhan, 

There are no define plan, but the issue has already been raised. 
I even had a draft branch that was doing something like that (https://github.com/Carreau/ipython/tree/_doc_star)
with nice HTML and equation rendering.

Still I think it have to be well thought to be correctly done. The issue I encounterd while writing this draft branch
were that you have several kind of syntax for docstrig (rst, numpy, …) so you probably need to decorate them
to declare their 'type'. (possibly using annotations  on python 3)

The other is that it is nice to have pretty docstring written in html or else, but then they are unreadable in plaintext.

So IMHO, the correct way to do that would be to 'declare' the format either at module level and/or with decorators, 
so that you can process the docstoring , either to convert it to plaintext, or html…. etc. 
Kind of replicating the _repr_*_ of object in IPython but with docstrings.

The second problem is often that generated doc with sphinx are parsed on the whole module at once, allowing custom
cross-link between classes/project. Which is not doable when you parse docstring live. Also docstring that have graphs and
everything can take a huge time to generate, and the generation can possibly fail. ( if you don't have matplotlib fofr example)

So one possible way would be to add a link to locally builded/downloaded documentation, or a magic that would build the doc for a specific module.
We could also provide a link to the page of official documentation, but probably not embed it for security reason.

In any way, if you wish to work on that, we can give you pointers. But I think the first thing to do would be to lay down
the requirement and the possible way to do do it. It will also probably need a spec change on object_info_request and a bump in 
protocol version.

Thanks, 
-- 
Matthias





Le 24 janv. 2013 à 04:03, Gökhan Sever a écrit :

> Hello,
> 
> Is there any plan for IPython notebook to support pretty rendering of docstrings?
> 
> Take for instance:
> 
> http://docs.scipy.org/doc/numpy/reference/generated/numpy.random.lognormal.html
> 
> Sphinx puts a nice rendered equation (probably via MathJax), right below:
> 
> "The probability density function for the log-normal distribution is"
> 
> and the layout of documentation is quite neat.
> 
> Sage notebook also renders the equation fine. Can this be supported in IPython notebook?
> 
> I am particularly interested in equation rendering, since I am planning to insert latex representation of the equations in function docstrings.
> 
> Thanks.
> 
> -- 
> Gökhan
> _______________________________________________
> IPython-User mailing list
> IPython-User@scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-user

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/ipython-user/attachments/20130124/b081bf3f/attachment.html 


More information about the IPython-User mailing list