[IPython-User] Pretty rendering of docstrings

Gökhan Sever gokhansever@gmail....
Thu Jan 24 12:25:27 CST 2013


Hi Matthias,

Glad to hear that previously this has been considered at least. However,
your description looks quite some work to me. I don't think, I can
participate much in the core development part of this task, but I
can definitely be help for testing of the implementation.

On Thu, Jan 24, 2013 at 1:06 AM, Matthias BUSSONNIER <
bussonniermatthias@gmail.com> wrote:

> 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
>
>
>
> _______________________________________________
> IPython-User mailing list
> IPython-User@scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-user
>
>


-- 
Gökhan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/ipython-user/attachments/20130124/6eba0b60/attachment.html 


More information about the IPython-User mailing list