matplotlib-devel Mailing List for matplotlib

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.
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....
Enjoy your vacation.
JDH

On Fri, May 23, 2008 at 5:50 PM, Eric Firing <ef...@ha...> wrote:
> With all the commits coming in, I thought I would try running
> backend_driver.py Template to make sure things were still working. When
> it got to mri_with_eeg, it stopped, initially cpu use was pegged, then
> my feisty box went into swap hell. It took about 5 minutes to extract
> it; Ctrl-Cing the python process was not enough.
>
> Anyone have any idea what might have gone wrong? I also tried running
> mri_with_eeg standalone, with gtkAgg backend, and it again ran away. I
> stopped it before it rendered the machine completely unresponsive.
It appears the hist call is killing it (comment out that one line and
it runs fine).
Manuel recently made some changes to hist to support 2D arrays: a
nsamples x nvariables array will generate nvariables different
histograms lined up side by side. In mir_with_eeg, the image data is
going into hist with shape (1, 28399) so it is trying to do 28399
histograms with one element each. I added some logic to handle this
case:
 x = np.asarray(x).copy()
 if len(x.shape)==2 and min(x.shape)==1:
 x.shape = max(x.shape),
 if len(x.shape)==2 and x.shape[0]<x.shape[1]:
 warnings.warn('2D hist should be nsamples x nvariables;
this looks transposed')
mri_with_eeg is working fine again in svn.
Manuel -- sorry I haven't gotten time to comment on the hist changes
but I think this is a very nice addition so thanks for adding it.
Just a reminder: when you make changes, it is good habit to run the
backend_driver.py example which may catch something you forgot to
test. BTW - the new examples in histogram_demo_extended.py look
great.
JDH

On Friday 23 May 2008 6:06:30 pm Eric Firing wrote:
> > xcorr(*args, **kwargs)
> > XCORR(x, y, normed=False, detrend=mlab.detrend_none,
> > usevlines=False, **kwargs):
>
> Sorry I'm not helping yet, but while you are in the middle of all this,
> please ditch the ugly and misleading Matlab-style capitalization of the
> function names.
>
> Thanks for all the work and amazing progress.
Some of these docstrings are *really* hard to trace. Where does pyplot.arrow 
get its docstring? It looks like it comes from axes.arrow, which gets a bit 
from patches.FancyArrow, which gets a bit from patches.Patch, which gets a 
bit from artist.kwdocd['Patch'] at the top of patches.py. However, I have 
completely rewritten artist.kwdocd['Patch']:
artist.kwdocd['Patch'] = """
 ================= ==============================================
 Property Description
 ================= ==============================================
 alpha float
 animated [True | False]
 antialiased or aa [True | False]
 clip_box a matplotlib.transform.Bbox instance
 clip_on [True | False]
 edgecolor or ec any matplotlib color
 facecolor or fc any matplotlib color
 figure a matplotlib.figure.Figure instance
 fill [True | False]
 hatch unknown
 label any string
 linewidth or lw float
 lod [True | False]
 transform a matplotlib.transform transformation instance
 visible [True | False]
 zorder any number
 ================= ==============================================
 """
but the change has not propagated up to pyplot.arrow.
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).
Darren

On Fri, May 23, 2008 at 4:59 PM, Tony Yu <ts...@gm...> wrote:
> As you can tell, I'm not an experienced programmer. In any case, I've
> attached a patch of "backend_wx.py" for the v0_91_maint branch. I didn't
> know if I was supposed to do something with the filepaths in the patch
> before sending it.
Hey Tony -- thanks for the patch -- it looks like you rapidly are
becoming a developer :-)
Could I ask you to submit a svn diff of the maintenance branch -- this
will be easier for me to apply. simoply make your changes in the
branch and then do
> svn diff > my.patch
and send that.
I think your icons look nice, but I was surprised that they were
grayscale. Is this a minimalist aesthetic?
Also, please keep all replies on list rather than to me personally
because someone else could be the one to ultimately handle the patch.
JDH

With all the commits coming in, I thought I would try running 
backend_driver.py Template to make sure things were still working. When 
it got to mri_with_eeg, it stopped, initially cpu use was pegged, then 
my feisty box went into swap hell. It took about 5 minutes to extract 
it; Ctrl-Cing the python process was not enough.
Anyone have any idea what might have gone wrong? I also tried running 
mri_with_eeg standalone, with gtkAgg backend, and it again ran away. I 
stopped it before it rendered the machine completely unresponsive.
Eric

> xcorr(*args, **kwargs)
> XCORR(x, y, normed=False, detrend=mlab.detrend_none,
> usevlines=False, **kwargs):
Sorry I'm not helping yet, but while you are in the middle of all this, 
please ditch the ugly and misleading Matlab-style capitalization of the 
function names.
Thanks for all the work and amazing progress.
Eric

On May 23, 2008, at 4:47 PM, John Hunter wrote:
> On Fri, May 23, 2008 at 2:00 PM, Tony Yu <ts...@gm...> wrote:
>> Hi,
>>
>> I apologize if this isn't the right forum for this email; I'm not
>> actually a matplotlib developer.
>>
>> I was trying to use custom icons for the mpl Wx backend, but the
>> version of mpl I was using had a _load_bitmap method that only read
>> xpm bitmaps. This requirement is enforced by the wx.BITMAP_TYPE_XPM
>> flag on:
>>
>> line 1398 of backend_wx.py in trunk
>> line 1458 of backend_wx.py in v0_91_maint
>>
>> The default flag wx.BITMAP_TYPE_ANY allows wx to autodetect the
>> format. Deleting the wx. BITMAP_TYPE_XPM argument allows me to change
>> to toolbar icons to png files. I noticed that the trunk and
>> v0_91_maint versions of mpl have a _load_pngicon method to load png
>> icons. This additional method seems unnecessary (or am I missing
>> something) if the offending argument is deleted.
>
> We made these changes recently on the advice of a user, but I am no wx
> guru. If you can post a patch that behaves properly and uses the png
> icons (the xpms don't render properly on some platforms). that would
> be great.
I'd like to try, but I've never contributed to a software project so 
submitting a patch seems pretty daunting. I'll have to read up on how 
to do this.
>
>
>> One final note: I made some new icons for the toolbars of the plot
>> windows. I'm not sure if many people would be interested in them 
>> since
>> I've made them following a OS X aesthetic (also, I replaced the home
>> icon with a reload icon because that made more sense to me). In any
>> case, I'd like to make these available as an alternative, but I'm not
>> sure where to post them.
>
> post them here as a small screenshot or just attach the icons. They
> can't be that large. I'm the list moderator so I can approve it if
> there is a problem. What I'd really like to see is a patch that
> allows users to customize the toolbar, eg by adding buttons, removing
> buttons, or changing the icons. This is not easy, especially across
> the user interfaces. Our toolbars would need to expose some common
> api for this...
Here are the pngs:

On Friday 23 May 2008 04:57:24 pm John Hunter wrote:
> On Fri, May 23, 2008 at 3:47 PM, Darren Dale <dar...@co...> 
wrote:
> >> so I have to get to work creating a new cool mpl figure for the logo.
> >> Our old banner is so 70s.
> >
> > I wasn't going to say it... but yeah. :)
>
> Thanks for your sensitivity :-)
haha! I hope you stick with your eeg, its just the colorscheme and fonts that 
are outdated.
> I made that a long time ago when I was 
> really proud that I could set the font size on text!
>
> > I think we need to set a policy on how we are going to handle code in
> > docstrings. There are lots of places where indentation and asterisks are
> > causing trouble. Should examples be codeblocks (::) or doctests (>>>)? I
> > think inlines should just be `` quoted, like:
> >
> > data are plotted as ``plot(lags, c, **kwargs)``
>
> Works for me -- we should prefer code blocks whether than inlines just
> because they are more readable w/o the quotes, but if we need inlines
> in some cases we'll use 'em
>
> > Here is an example from axes.Axes:
> >
> > def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none,
> > usevlines=False, maxlags=None, **kwargs):
> > """
> > XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False,
> > **kwargs):a
> >
> > Can we eliminate the call signature? I think this is only necessary for
> > extension code, the call signature will already be displayed by sphinx
> > and by pythons interactive help.
>
> Unfortunately, I think we need it. pyplot xcorr is just a *args,
> **kwargs pass though to Axes.xcorr, so if you do help pyplot.xcorr you
> won't see the signature, which is why we manually copy the signature
> in axes.py.
Oh, right.
> In [89]: help pyplot.xcorr
> Help on function xcorr in module matplotlib.pyplot:
>
> xcorr(*args, **kwargs)
> XCORR(x, y, normed=False, detrend=mlab.detrend_none,
> usevlines=False, **kwargs):
>
> Plot the cross correlation between x and y. If normed=True,
> normalize the data but the cross correlation at 0-th lag. x
> and y are detrended by the detrend callable (default no
> normalization. x and y must be equal length
>
> We could use a codeblock in axes.py
> def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none,
> usevlines=False,
> maxlags=None, **kwargs):
> """
> pyplot signature:
>
> xcorr(x, y, normed=False, detrend=mlab.detrend_none,
> usevlines=False, **kwargs):
>
> Plot the cross correlation between x and y. If normed=True,
> normalize the data but the cross correlation at 0-th lag. x
> and y are detrended by the detrend callable (default no
How about Use:, or Usage: or Signature:? Most of these exist outside of 
pyplot.

On Fri, May 23, 2008 at 3:47 PM, Darren Dale <dar...@co...> wrote:
>> so I have to get to work creating a new cool mpl figure for the logo.
>> Our old banner is so 70s.
>
> I wasn't going to say it... but yeah. :)
Thanks for your sensitivity :-) I made that a long time ago when I was
really proud that I could set the font size on text!
> I think we need to set a policy on how we are going to handle code in
> docstrings. There are lots of places where indentation and asterisks are
> causing trouble. Should examples be codeblocks (::) or doctests (>>>)? I
> think inlines should just be `` quoted, like:
>
> data are plotted as ``plot(lags, c, **kwargs)``
Works for me -- we should prefer code blocks whether than inlines just
because they are more readable w/o the quotes, but if we need inlines
in some cases we'll use 'em
> Here is an example from axes.Axes:
>
> def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none,
> usevlines=False, maxlags=None, **kwargs):
> """
> XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False,
> **kwargs):a
>
> Can we eliminate the call signature? I think this is only necessary for
> extension code, the call signature will already be displayed by sphinx and by
> pythons interactive help.
Unfortunately, I think we need it. pyplot xcorr is just a *args,
**kwargs pass though to Axes.xcorr, so if you do help pyplot.xcorr you
won't see the signature, which is why we manually copy the signature
in axes.py.
 In [89]: help pyplot.xcorr
 Help on function xcorr in module matplotlib.pyplot:
 xcorr(*args, **kwargs)
 XCORR(x, y, normed=False, detrend=mlab.detrend_none,
usevlines=False, **kwargs):
 Plot the cross correlation between x and y. If normed=True,
 normalize the data but the cross correlation at 0-th lag. x
 and y are detrended by the detrend callable (default no
 normalization. x and y must be equal length
We could use a codeblock in axes.py
 def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none,
usevlines=False,
 maxlags=None, **kwargs):
 """
 pyplot signature:
 xcorr(x, y, normed=False, detrend=mlab.detrend_none,
usevlines=False, **kwargs):
 Plot the cross correlation between x and y. If normed=True,
 normalize the data but the cross correlation at 0-th lag. x
 and y are detrended by the detrend callable (default no
> Regarding the crazy pyplot error, I'm doing it the slow, painful way,
> including a few members at a time in the members list and fixing the errors
> that arise.
Ugg, I don't envy you. Perhaps a message to the maintainer about the
need for some verbose context in these error messages would be more
expeditious. We have a lot of these to do.
Another feature I'd like to see is a macro location parameter. Eg
 define location:`mplexamples` = ../../examples/pyplot
and then later be able to refer to that
 .. literalinclude:: location:`mplexamples`/simple_plot.py
with whatever syntax is appropriate so as we reorganize we don't have
to keep fixing the relative path structure. Eg, I am including icons
from mpl/data/images in the navigation toolbar section....
JDH

On Fri, May 23, 2008 at 2:00 PM, Tony Yu <ts...@gm...> wrote:
> Hi,
>
> I apologize if this isn't the right forum for this email; I'm not
> actually a matplotlib developer.
>
> I was trying to use custom icons for the mpl Wx backend, but the
> version of mpl I was using had a _load_bitmap method that only read
> xpm bitmaps. This requirement is enforced by the wx.BITMAP_TYPE_XPM
> flag on:
>
> line 1398 of backend_wx.py in trunk
> line 1458 of backend_wx.py in v0_91_maint
>
> The default flag wx.BITMAP_TYPE_ANY allows wx to autodetect the
> format. Deleting the wx. BITMAP_TYPE_XPM argument allows me to change
> to toolbar icons to png files. I noticed that the trunk and
> v0_91_maint versions of mpl have a _load_pngicon method to load png
> icons. This additional method seems unnecessary (or am I missing
> something) if the offending argument is deleted.
We made these changes recently on the advice of a user, but I am no wx
guru. If you can post a patch that behaves properly and uses the png
icons (the xpms don't render properly on some platforms). that would
be great.
> One final note: I made some new icons for the toolbars of the plot
> windows. I'm not sure if many people would be interested in them since
> I've made them following a OS X aesthetic (also, I replaced the home
> icon with a reload icon because that made more sense to me). In any
> case, I'd like to make these available as an alternative, but I'm not
> sure where to post them.
post them here as a small screenshot or just attach the icons. They
can't be that large. I'm the list moderator so I can approve it if
there is a problem. What I'd really like to see is a patch that
allows users to customize the toolbar, eg by adding buttons, removing
buttons, or changing the icons. This is not easy, especially across
the user interfaces. Our toolbars would need to expose some common
api for this...
JDH

On Friday 23 May 2008 04:34:11 pm John Hunter wrote:
> On Fri, May 23, 2008 at 3:31 PM, Darren Dale <dar...@co...> 
wrote:
> > commit yout customizing.txt?
>
> done.
>
> I just discovered l
>
>
> # The name of an image file (within the static path) to place at the
> top of # the sidebar.
> #html_logo = 'logo.png'
>
> so I have to get to work creating a new cool mpl figure for the logo.
> Our old banner is so 70s.
I wasn't going to say it... but yeah. :)
I think we need to set a policy on how we are going to handle code in 
docstrings. There are lots of places where indentation and asterisks are 
causing trouble. Should examples be codeblocks (::) or doctests (>>>)? I 
think inlines should just be `` quoted, like:
data are plotted as ``plot(lags, c, **kwargs)``
Here is an example from axes.Axes:
def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, 
 usevlines=False, maxlags=None, **kwargs):
 """
 XCORR(x, y, normed=False, detrend=mlab.detrend_none, usevlines=False, 
 **kwargs):a 
Can we eliminate the call signature? I think this is only necessary for 
extension code, the call signature will already be displayed by sphinx and by 
pythons interactive help.
Regarding the crazy pyplot error, I'm doing it the slow, painful way, 
including a few members at a time in the members list and fixing the errors 
that arise.
Darren

On Fri, May 23, 2008 at 3:31 PM, Darren Dale <dar...@co...> wrote:
> commit yout customizing.txt?
done.
I just discovered l
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
 #html_logo = 'logo.png'
so I have to get to work creating a new cool mpl figure for the logo.
Our old banner is so 70s.
JDH

On Friday 23 May 2008 04:12:51 pm John Hunter wrote:
> On Fri, May 23, 2008 at 3:00 PM, Darren Dale <dar...@co...> 
wrote:
> > On Friday 23 May 2008 03:02:55 pm John Hunter wrote:
> >> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> wrote:
> >> > It certainly would make the docs more useful to be able to link to the
> >> > class and function references. Argg. I guess I'll just have to give
> >> > up my desire to have clean ASCII here, since most people are going to
> >> > read this on the web or as PDF so we should target that. One
> >> > question: suppose we use class:`Line2D` and include the reference docs
> >> > in a single build, eg for the web site and a master PDF, but we want
> >> > to provide on some occasions a lighter PDF, eg just a few of the docs
> >> > w/o the reference. Will sphinx be somewhat smart and just format the
> >> > class:`Line2D` as monospace when it cannot find the references?
> >>
> >> I've been experimenting with including the api docs in the same build
> >> to see if I could get linking to work, eg links in the pyplot tutorial
> >> to matplotlib.lines.Line2D. I know if we go this route some more
> >> reorganization will be needed, so we should figure that out and get
> >> our commits in and then freeze while Darren does the reorg.
> >
> > I was able to get the linking to work, as I posted in my last message,
> > but forgot to address a reorg. I'm happy to do it, but I will be out of
> > town and away from a computer Saturday morning through Monday afternoon.
> > If we decide to include the api in the users guide (I think it is worth
> > considering), I can do it when I get back.
>
> OK, sounds good.
>
> I tried including the pyplot reference docs but it is croaking on the
> docstrings there. I suppose some of them have some invalid rest.
> Unfortunately the line numbers don't make a lot of sense
>
> updating environment: 17 added, 0 changed, 0 removed
> reading... add_new_projection api api_artists api_introduction
> api_pyplot reST markup error:
> 
> /home/titan/johnh/python/svn/matplotlib.trunk/matplotlib/doc/users_guide/ap
>i_pyplot.txt:1127: (SEVERE/4) Unexpected section title or transition.
>
> ****************
>
>
> since api_pyplt.txt is just a small file which does:
>
> *****************
> matplotlib.pyplot
> *****************
>
> :mod:`matplotlib.pyplot`
>
> =============================
>
> .. automodule:: matplotlib.pyplot
>
> :members:
> :undoc-members:
>
> Have you had any success in figuring out how to know what is causing
> these kinds of errors, ie where to go in the module docs to fix them?
No, I was just having a look at that myself. Usually it gives you a little 
more to go on, like these which are now fixed except for the last one:
WARNING: <docstring of matplotlib.artist.ArtistInspector.get_aliases>:4: 
(ERROR/3) Unexpected indentation.
WARNING: <docstring of matplotlib.lines.unmasked_index_ranges>:17: (ERROR/3) 
Unexpected indentation.
WARNING: <docstring of matplotlib.lines.unmasked_index_ranges>:25: (ERROR/3) 
Unexpected indentation.
WARNING: /usr/local/src/matplotlib/matplotlib/doc/users_guide/users_guide.txt:7: 
(WARNING/2) toctree references unknown document u'customizing'
Could you commit yout customizing.txt?

On Fri, May 23, 2008 at 3:00 PM, Darren Dale <dar...@co...> wrote:
> On Friday 23 May 2008 03:02:55 pm John Hunter wrote:
>> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> wrote:
>> > It certainly would make the docs more useful to be able to link to the
>> > class and function references. Argg. I guess I'll just have to give
>> > up my desire to have clean ASCII here, since most people are going to
>> > read this on the web or as PDF so we should target that. One
>> > question: suppose we use class:`Line2D` and include the reference docs
>> > in a single build, eg for the web site and a master PDF, but we want
>> > to provide on some occasions a lighter PDF, eg just a few of the docs
>> > w/o the reference. Will sphinx be somewhat smart and just format the
>> > class:`Line2D` as monospace when it cannot find the references?
>>
>> I've been experimenting with including the api docs in the same build
>> to see if I could get linking to work, eg links in the pyplot tutorial
>> to matplotlib.lines.Line2D. I know if we go this route some more
>> reorganization will be needed, so we should figure that out and get
>> our commits in and then freeze while Darren does the reorg.
>
> I was able to get the linking to work, as I posted in my last message, but
> forgot to address a reorg. I'm happy to do it, but I will be out of town and
> away from a computer Saturday morning through Monday afternoon. If we decide
> to include the api in the users guide (I think it is worth considering), I
> can do it when I get back.
OK, sounds good.
I tried including the pyplot reference docs but it is croaking on the
docstrings there. I suppose some of them have some invalid rest.
Unfortunately the line numbers don't make a lot of sense
 updating environment: 17 added, 0 changed, 0 removed
 reading... add_new_projection api api_artists api_introduction
api_pyplot reST markup error:
 /home/titan/johnh/python/svn/matplotlib.trunk/matplotlib/doc/users_guide/api_pyplot.txt:1127:
(SEVERE/4) Unexpected section title or transition.
 ****************
since api_pyplt.txt is just a small file which does:
 *****************
 matplotlib.pyplot
 *****************
 :mod:`matplotlib.pyplot`
 =============================
 .. automodule:: matplotlib.pyplot
 :members:
 :undoc-members:
Have you had any success in figuring out how to know what is causing
these kinds of errors, ie where to go in the module docs to fix them?
JDH

On Friday 23 May 2008 03:02:55 pm John Hunter wrote:
> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> wrote:
> > It certainly would make the docs more useful to be able to link to the
> > class and function references. Argg. I guess I'll just have to give
> > up my desire to have clean ASCII here, since most people are going to
> > read this on the web or as PDF so we should target that. One
> > question: suppose we use class:`Line2D` and include the reference docs
> > in a single build, eg for the web site and a master PDF, but we want
> > to provide on some occasions a lighter PDF, eg just a few of the docs
> > w/o the reference. Will sphinx be somewhat smart and just format the
> > class:`Line2D` as monospace when it cannot find the references?
>
> I've been experimenting with including the api docs in the same build
> to see if I could get linking to work, eg links in the pyplot tutorial
> to matplotlib.lines.Line2D. I know if we go this route some more
> reorganization will be needed, so we should figure that out and get
> our commits in and then freeze while Darren does the reorg.
I was able to get the linking to work, as I posted in my last message, but 
forgot to address a reorg. I'm happy to do it, but I will be out of town and 
away from a computer Saturday morning through Monday afternoon. If we decide 
to include the api in the users guide (I think it is worth considering), I 
can do it when I get back.
We can potentially pare back the size of the api reference, since we have some 
control over what is and is not included.
Darren

On Friday 23 May 2008 03:02:55 pm John Hunter wrote:
> On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> wrote:
> > It certainly would make the docs more useful to be able to link to the
> > class and function references. Argg. I guess I'll just have to give
> > up my desire to have clean ASCII here, since most people are going to
> > read this on the web or as PDF so we should target that. One
> > question: suppose we use class:`Line2D` and include the reference docs
> > in a single build, eg for the web site and a master PDF, but we want
> > to provide on some occasions a lighter PDF, eg just a few of the docs
> > w/o the reference. Will sphinx be somewhat smart and just format the
> > class:`Line2D` as monospace when it cannot find the references?
>
> I've been experimenting with including the api docs in the same build
> to see if I could get linking to work, eg links in the pyplot tutorial
> to matplotlib.lines.Line2D. I know if we go this route some more
> reorganization will be needed, so we should figure that out and get
> our commits in and then freeze while Darren does the reorg. But I am
> having trouble in that my class links are not recognized, even though
> I've added the relevant module to the api_artists.txt file which is
> included by api.txt which is included by indext.txt which builds
> everything. Any ideas?
If a member doesnt contain a docstring, it wont be included by autodoc, at 
least by default. You can change this by adding the undoc-members flag:
:mod:`matplotlib.lines`
=============================
.. automodule:: matplotlib.lines
 :members:
 :undoc-members:
So Line2D was not showing up in the api chapter.
I added that line in the trunk, deleted my build directory, and I can see the 
link now.
Darren
-- 
Darren S. Dale, Ph.D.
Staff Scientist
Cornell High Energy Synchrotron Source
Cornell University
275 Wilson Lab
Rt. 366 & Pine Tree Road
Ithaca, NY 14853
dar...@co...
office: (607) 255-3819
fax: (607) 255-9001
http://www.chess.cornell.edu

On Friday 23 May 2008 02:00:57 pm Michael Droettboom wrote:
> John Hunter wrote:
> > On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <md...@st...> 
wrote:
> >> For my fellow emacs users:
> >>
> >> If you aren't aware of it, there is a reST mode for emacs:
> >>
> >> http://docutils.sourceforge.net/tools/editors/emacs/rst.el
> >>
> >> In the course of experimenting today, I wrote a few elisp macros
> >> (attached) to aid in adding inline cross-references to the code that
> >> might be generally useful. By putting the cursor over a particular
> >> token, you can easily mark it as a class, function, method, module etc. 
> >> For example, pressing "C-c c" over the word "Axes" will replace it with
> >> ":class:`Axes`".
> >
> > Will rest recognize the module this comes from?- I've been using the
> > full path :class:`matplotlib.lines.Line2D` and when I just want the
> > Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't
> > tested this yet since we don't have the api docs linked in, but this
> > is how I've been writing...
>
> From the playing around I've done, it seems that, yes, you do need to
> fully specify if you're writing from outside of a docstring. However
> within docstrings, it seems you can refer to other methods in the same
> class or other classes in the same module by their name only.
>
> (My emacs macros are a little broken because they stop at '.'s, but
> hopefully I can fix that without going too crazy.)
I just discovered the figure directive:
.. literalinclude:: figures/pyplot_simple.py
.. figure:: figures/pyplot_simple.png
 :scale: 50
 Here's a caption!
Its not obvious in the html output that it is a caption, but in the latex 
output it uses the figure environment and so a caption yields a figure 
number.
Is there a prefered size for the figures? The html figures are currently a 
little large for my taste, and the pdf figures are a little small.
One last thing, I wonder if it would be worth pursuing the ability to include 
pdf files in the latex document. Maybe Georg would accept a patch that 
attempts to do the right thing if the extension is missing?
Darren

On Fri, May 23, 2008 at 9:54 AM, John Hunter <jd...@gm...> wrote:
> It certainly would make the docs more useful to be able to link to the
> class and function references. Argg. I guess I'll just have to give
> up my desire to have clean ASCII here, since most people are going to
> read this on the web or as PDF so we should target that. One
> question: suppose we use class:`Line2D` and include the reference docs
> in a single build, eg for the web site and a master PDF, but we want
> to provide on some occasions a lighter PDF, eg just a few of the docs
> w/o the reference. Will sphinx be somewhat smart and just format the
> class:`Line2D` as monospace when it cannot find the references?
I've been experimenting with including the api docs in the same build
to see if I could get linking to work, eg links in the pyplot tutorial
to matplotlib.lines.Line2D. I know if we go this route some more
reorganization will be needed, so we should figure that out and get
our commits in and then freeze while Darren does the reorg. But I am
having trouble in that my class links are not recognized, even though
I've added the relevant module to the api_artists.txt file which is
included by api.txt which is included by indext.txt which builds
everything. Any ideas?
JDH

Hi,
I apologize if this isn't the right forum for this email; I'm not 
actually a matplotlib developer.
I was trying to use custom icons for the mpl Wx backend, but the 
version of mpl I was using had a _load_bitmap method that only read 
xpm bitmaps. This requirement is enforced by the wx.BITMAP_TYPE_XPM 
flag on:
line 1398 of backend_wx.py in trunk
line 1458 of backend_wx.py in v0_91_maint
The default flag wx.BITMAP_TYPE_ANY allows wx to autodetect the 
format. Deleting the wx. BITMAP_TYPE_XPM argument allows me to change 
to toolbar icons to png files. I noticed that the trunk and 
v0_91_maint versions of mpl have a _load_pngicon method to load png 
icons. This additional method seems unnecessary (or am I missing 
something) if the offending argument is deleted.
One final note: I made some new icons for the toolbars of the plot 
windows. I'm not sure if many people would be interested in them since 
I've made them following a OS X aesthetic (also, I replaced the home 
icon with a reload icon because that made more sense to me). In any 
case, I'd like to make these available as an alternative, but I'm not 
sure where to post them.
Thanks in advance for reading my ramblings.
-Tony

John Hunter wrote:
> On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <md...@st...> wrote:
> 
>> For my fellow emacs users:
>>
>> If you aren't aware of it, there is a reST mode for emacs:
>>
>> http://docutils.sourceforge.net/tools/editors/emacs/rst.el
>>
>> In the course of experimenting today, I wrote a few elisp macros (attached)
>> to aid in adding inline cross-references to the code that might be generally
>> useful. By putting the cursor over a particular token, you can easily mark
>> it as a class, function, method, module etc. For example, pressing "C-c c"
>> over the word "Axes" will replace it with ":class:`Axes`".
>> 
>
> Will rest recognize the module this comes from?- I've been using the
> full path :class:`matplotlib.lines.Line2D` and when I just want the
> Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't
> tested this yet since we don't have the api docs linked in, but this
> is how I've been writing...
> 
 From the playing around I've done, it seems that, yes, you do need to 
fully specify if you're writing from outside of a docstring. However 
within docstrings, it seems you can refer to other methods in the same 
class or other classes in the same module by their name only.
(My emacs macros are a little broken because they stop at '.'s, but 
hopefully I can fix that without going too crazy.)
Cheers,
Mike
-- 
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

On Fri, May 23, 2008 at 11:59 AM, Michael Droettboom <md...@st...> wrote:
> For my fellow emacs users:
>
> If you aren't aware of it, there is a reST mode for emacs:
>
> http://docutils.sourceforge.net/tools/editors/emacs/rst.el
>
> In the course of experimenting today, I wrote a few elisp macros (attached)
> to aid in adding inline cross-references to the code that might be generally
> useful. By putting the cursor over a particular token, you can easily mark
> it as a class, function, method, module etc. For example, pressing "C-c c"
> over the word "Axes" will replace it with ":class:`Axes`".
Will rest recognize the module this comes from?- I've been using the
full path :class:`matplotlib.lines.Line2D` and when I just want the
Line2D w/o the full path :class:`~matplotlib.lines.Line2D`. I haven't
tested this yet since we don't have the api docs linked in, but this
is how I've been writing...

For my fellow emacs users:
If you aren't aware of it, there is a reST mode for emacs:
http://docutils.sourceforge.net/tools/editors/emacs/rst.el
In the course of experimenting today, I wrote a few elisp macros 
(attached) to aid in adding inline cross-references to the code that 
might be generally useful. By putting the cursor over a particular 
token, you can easily mark it as a class, function, method, module etc. 
For example, pressing "C-c c" over the word "Axes" will replace it with 
":class:`Axes`".
C-c c : class
C-c m : method
C-c f : function
C-c a : attribute
C-c o : module
Cheers,
Mike
John Hunter wrote:
> On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> wrote:
>
> 
>> Personally, I would prefer to see all the names in monospaced type (I find
>> it much more readable), but the additional markup may be somewhat at odds
>> with keeping the original ReST source clean. There are also two roads to
>> take: a) simply putting `` around them, or b) using the Sphinx
>> cross-referencing constructs, e.g. ":class:`Line2D`".
>>
>> b) is obviously a lot noisier in the original ReST, but could produce more
>> useful online documentation. Note, however, that if we put the narrative
>> and reference documentation in separate documents, the cross-references
>> won't actually work between them.
>> 
>
> It certainly would make the docs more useful to be able to link to the
> class and function references. Argg. I guess I'll just have to give
> up my desire to have clean ASCII here, since most people are going to
> read this on the web or as PDF so we should target that. One
> question: suppose we use class:`Line2D` and include the reference docs
> in a single build, eg for the web site and a master PDF, but we want
> to provide on some occasions a lighter PDF, eg just a few of the docs
> w/o the reference. Will sphinx be somewhat smart and just format the
> class:`Line2D` as monospace when it cannot find the references?
>
> JDH
> 
-- 
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

On Friday 23 May 2008 10:56:47 am Michael Droettboom wrote:
> Michael Droettboom wrote:
> > Secondly, the ipython console sessions aren't getting syntax highlighted
> > -- it would be nice if they did, particularly to indicate input vs.
> > output. I'll volunteer to look into this -- I've done some pygments
> > customization work in the past and maybe it won't be too difficult.
>
> I just committed support for this on the trunk. The usage is not
> automatic. The reST code must specifically request it using the
> ..sourcecode directive:
>
> .. sourcecode:: ipython
>
> In [101]: ax.lines[0]
> Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>
>
> In [102]: line
> Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>
>
> Making this automatic would have required monkey-patching Sphinx --
> there doesn't seem to be an API to extend its algorithm to automatically
> select a syntax highlighter, as I suppose this requirement is somewhat
> obscure.
I think it might be worth mentioning on Sphinx-dev, there might be some 
interest in supporting it. As it is, though, I don't think 
".. sourcecode:: ipython" isn't much more distracting than, say:
blah blah::
 :ipython:
 In [101]: ax.lines[0]
 Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710>
 In [102]: line
 Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710>
Darren

On Friday 23 May 2008 10:54:52 am John Hunter wrote:
> On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> wrote:
> > Personally, I would prefer to see all the names in monospaced type (I
> > find it much more readable), but the additional markup may be somewhat at
> > odds with keeping the original ReST source clean. There are also two
> > roads to take: a) simply putting `` around them, or b) using the Sphinx
> > cross-referencing constructs, e.g. ":class:`Line2D`".
> >
> > b) is obviously a lot noisier in the original ReST, but could produce
> > more useful online documentation. Note, however, that if we put the
> > narrative and reference documentation in separate documents, the
> > cross-references won't actually work between them.
>
> It certainly would make the docs more useful to be able to link to the
> class and function references. Argg. I guess I'll just have to give
> up my desire to have clean ASCII here, since most people are going to
> read this on the web or as PDF so we should target that. One
> question: suppose we use class:`Line2D` and include the reference docs
> in a single build, eg for the web site and a master PDF, but we want
> to provide on some occasions a lighter PDF, eg just a few of the docs
> w/o the reference. Will sphinx be somewhat smart and just format the
> class:`Line2D` as monospace when it cannot find the references?
I just committed a few changes so equations can be rendered using the mathpng 
extension. The syntax is shown in the documenting_mpl.txt.

John Hunter wrote:
> On Fri, May 23, 2008 at 8:12 AM, Michael Droettboom <md...@st...> wrote:
>
> 
>> Personally, I would prefer to see all the names in monospaced type (I find
>> it much more readable), but the additional markup may be somewhat at odds
>> with keeping the original ReST source clean. There are also two roads to
>> take: a) simply putting `` around them, or b) using the Sphinx
>> cross-referencing constructs, e.g. ":class:`Line2D`".
>>
>> b) is obviously a lot noisier in the original ReST, but could produce more
>> useful online documentation. Note, however, that if we put the narrative
>> and reference documentation in separate documents, the cross-references
>> won't actually work between them.
>> 
>
> It certainly would make the docs more useful to be able to link to the
> class and function references. Argg. I guess I'll just have to give
> up my desire to have clean ASCII here, since most people are going to
> read this on the web or as PDF so we should target that. One
> question: suppose we use class:`Line2D` and include the reference docs
> in a single build, eg for the web site and a master PDF, but we want
> to provide on some occasions a lighter PDF, eg just a few of the docs
> w/o the reference. Will sphinx be somewhat smart and just format the
> class:`Line2D` as monospace when it cannot find the references?
> 
It appears to. See, for example, the :mod:`matplotlib.plab` that gets 
formatted in monospace in the introduction.
Cheers,
Mike
-- 
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA