[IPython-User] Pretty rendering of docstrings

Brian Granger ellisonbg@gmail....
Thu Jan 24 12:41:51 CST 2013


I know this is heresy, but the easiest docstring format for us to deal
with is markdown.  It would be nearly trivial for us to render that in
the  notebook along with embedded latex.  reST is horrible for this
type of thing - especially because it requires server side rendering,
which I am not excited about at all.

What about the following:

* By default we just render docstrings as text.
* We establish an informal protocol that allows doctstrings to declare
their own format (html, markdown, etc.).
* We use that information to determine how to render the docstring.

Obviously, people would have to start to write their docstrings in
this way, but it would at least set the stage for what can be done.
Personally, if the notebook became able to handle markdown+latex
docstrings, I would never user reST for any new project.

Cheers,

Brian


On Wed, Jan 23, 2013 at 7:03 PM, Gökhan Sever <gokhansever@gmail.com> wrote:
> 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
>



-- 
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com


More information about the IPython-User mailing list