On Wed, Jul 22, 2009 at 8:15 AM, Jouni K. Seppänen<jk...@ik...> 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. 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