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.