[SciPy-dev] Latex and docstrings

[John Hunter]

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.

As an example, compare the text rendered help for Text vs the html
rendered at http://matplotlib.sourceforge.net/api/artist_api.html#matplotlib.text.Text

Help on Text in module matplotlib.text object:

class Text(matplotlib.artist.Artist)
 |  Handle storing and drawing of text in window or data coordinates.
 |
 |  Method resolution order:
 |      Text
 |      matplotlib.artist.Artist
 |      __builtin__.object
 |
 |  Methods defined here:
 |
 |  __init__(self, x=0, y=0, text='', color=None,
verticalalignment='bottom', horizontalalignment='left',
multialignment=None, fontproperties=None, rotation=None,
linespacing=None, rotation_mode=None, path_effects=None,
**kwargs)text*.
 |
 |      Valid kwargs are
 |        agg_filter: unknown
 |        alpha: float (0.0 transparent through 1.0 opaque)
 |        animated: [True | False]
 |        axes: an :class:`~matplotlib.axes.Axes` instance
 |        backgroundcolor: any matplotlib color
 |        bbox: rectangle prop dict
 |        clip_box: a :class:`matplotlib.transforms.Bbox` instance
 |        clip_on: [True | False]