Better pyplot wrappers

Jouni K. Sepp�nen <jks@...278...> writes:

I now have two different implementations in two branches of my
github repository (patches attached):

http://github.com/jkseppan/matplotlib/tree/boilerplate
http://github.com/jkseppan/matplotlib/tree/autoboiler

I finally committed the "boilerplate" variant. It seems to pass the
tests in pylab_examples, but now might be a good time for everyone to
take a look to see if I have broken anything.

···

--
Jouni K. Sepp�nen
http://www.iki.fi/jks

There is one problem, but I am not sure what the workaround is yet.
The doc strings in rest are broken, eg compare the pyplot Line2D
properties with the Axes equivalent:

  http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.loglog

vs

  http://matplotlib.sourceforge.net/api/axes_api.html#matplotlib.axes.Axes.loglog

Both use the artist.kwdocs inspector to autogenerate the tables.
There is a rc param in doc/matplotlibrc which we use to force rest
formatting

  docstring.hardcopy : True # set this when you want to generate
hardcopy docstring

which is False by default for src installs and True when we build the
docs. Then in matplotlib.artist, we do

def kwdoc(a):
    hardcopy = matplotlib.rcParams['docstring.hardcopy']
    if hardcopy:
        return '\n'.join(ArtistInspector(a).pprint_setters_rest(leadingspace=2))
    else:
        return '\n'.join(ArtistInspector(a).pprint_setters(leadingspace=2))

to format rest when making hardcopy.

Then we we interpolate into the docstring at runtime::

   # from Axes.loglog

    def loglog(self, *args, **kwargs):
        """
        ...snip

        The remaining valid kwargs are
        :class:`~matplotlib.lines.Line2D` properties:

        %(Line2D)s

        **Example:**

        .. plot:: mpl_examples/pylab_examples/log_demo.py

        """
        ...snip
        return l

    loglog.__doc__ = cbook.dedent(loglog.__doc__) % martist.kwdocd

we get plain text when hardcopy is False and rest when it is True.
Thus we have the best of both worlds from the interactive shell and on
the website and PDF.

It looks like you are interpolating the strings in in boilerplate,
when they should be left to be interpolated *at runtime* as we do in
the other modules. Ie, it appears you are doing runtime interpolating
when you generate pyplot.py from boilerplate.py. In the old version,
the interpolation of pyplot doc strings were deferred
until runtime, eg from older pyplot.py::

# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
def loglog(*args, **kwargs):
    # allow callers to override the hold state by passing hold=True|False
    b = ishold()
    h = kwargs.pop('hold', None)
    if h is not None:
        hold(h)
    try:
        ret = gca().loglog(*args, **kwargs)
        draw_if_interactive()
    except:
        hold(b)
        raise

    hold(b)
    return ret
if Axes.loglog.__doc__ is not None:
    loglog.__doc__ = dedent(Axes.loglog.__doc__) + """

Additional kwargs: hold = [True|False] overrides default hold state"""

Is there a way to preserve this in the new boilerplate configuration?

JDH

···

On Wed, Jul 22, 2009 at 8:15 AM, Jouni K. Seppänen<jks@...278...> wrote:

I finally committed the "boilerplate" variant. It seems to pass the
tests in pylab_examples, but now might be a good time for everyone to
take a look to see if I have broken anything.