Re: [matplotlib-devel] future of mpl documentation

[Darren D. <dar...@co...>]

On Friday 23 May 2008 7:54:27 pm John Hunter wrote:
> On Fri, May 23, 2008 at 6:14 PM, Darren Dale <dar...@co...>
> wrote
>
> > I have to break here for the weekend, I'll be back monday afternoon.
> > Leave some for me! (although I'll owe doughnut to whoever can fix the
> > arrow docstring).
>
> I'll claim that doughnut.

When was the last time you received one in the mail?

(more at the end...)

> This is a bit complicated.  The problem is that we have to do the
> interpolation into the patch doc strings at class definition time (eg
> for Patch and Rectangle), but we can't use the object inspector and
> doc string generator artist.kwdoc to automatically generate them until
> *after* they are defined.  So we have a bit of a race condition.  The
> solution, which is not terribly elegant, is to define the string for
> the *classes* manually with the setting at the top of
> matplotlib.patches:
>
>   artist.kwdocd['Patch'] = """\
>           alpha: float
>           animated: [True | False]
>           antiali
>
> We interpolate this into the class docstrings.  Once the classes are
> defined, we can introspect the class and auto generate the strings for
> use in *methods* that operate on class instances.  At the bottom of
> patches:
>
>     artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
>
>     artist.kwdocd['Patch'] = patchdoc = artist.kwdoc(Patch)
>     for k in ('Rectangle', 'Circle', 'RegularPolygon', 'Polygon',
> 'Wedge', 'Arrow',
>               'FancyArrow', 'YAArrow', 'CirclePolygon', 'Ellipse'):
>         artist.kwdocd[k] = patchdoc
>
> so the changes you make in the kwdocd dict will affect the classes in
> matplotlib.patches, bu will not affect the docstrings in the plotting
> functions, eg matplotlib.axes.Axes.arrow, which will use the
> auto-generated version from artist.kwdoc.  So you need to make your
> changes in two places:  in the kwdocd dict at the top of patches, as
> you did before, *and* in the artist.kwdoc function which
> auto-generates the property tables.  If this function returns rest
> tables, you will be in good shape.  It is not good design to have to
> make the changes in two places, but when we implemented this we could
> not find a way to do the class doc string interpolation after the
> class was defined, but we still wanted to use the autogenerated docs
> where possible (eg in methods that handle artists like the plotting
> methods) since the auto-generated stuff is more likely to remain
> current.
>
> Maybe an entry in the developer's guide is warranted....

Thanks for the detailed explanation. I'm tagging the message so I can remember 
to include it in the developers guide. Now that I understand it, it wasn't 
too difficult to reformat the output into a ReST table. Onwards!

Darren