Re: [matplotlib-devel] ReST docs: figures

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

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