[SciPy-dev] Latex and docstrings

[Ralf Gommers]

On Thu, Feb 18, 2010 at 12:15 AM, John Hunter <jdh2358 at gmail.com> wrote:

> On Wed, Feb 17, 2010 at 6:21 AM, Ralf Gommers
> <ralf.gommers at googlemail.com> wrote:
>
> > Fixing this docstring for both terminal and html/pdf does not seem
> possible,
> > short of removing content or writing a new Sphinx plugin. For now I would
> be
> > in favor of keeping the latex, because going to the html doc for terminal
> > users is doable. Users of the html docs on the other hand are unlikely to
> > all know their way around a terminal.
>
> In mpl we have a related issue -- we render rest tables for the html
> and pdf, but ascii tables for the interactive docs (eg "help" in
> python)
>
> We achieve this by sacrificing the readability of the source
> docstrings, eg for Text
>
>    def __init__(self,
>                 ....
>                 **kwargs
>                 ):
>        """
>        Create a :class:`~matplotlib.text.Text` instance at *x*, *y*
>        with string *text*.
>
>        Valid kwargs are
>        %(Text)s
>        """
>
> and have a module for inserting formated strings into the docstrings
>
>   docstring.interpd.update(Text = artist.kwdoc(Text))
>
> This module respects an rc setting which determines whether to render
> in "hardcopy" mode or not.  numpy could adopt a similar system in
> which equations are interpolated in as either ascii or latex depending
> on a runtime setting.
>
> String substitutions are handy when you need to share content between
several objects, but imho is overkill for each equation you want to typeset.
Something like AsciiMathML would still be the ideal solution here.

It also won't work with the doc editor unless you make it aware of how the
substitution system works. Which is not trivial.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100218/c7b0ccf8/attachment.html>