Documentation: New plot directive

Development matplotlib-devel
1

I have added a new "plot" directive to our doc infrastructure that does:

"""
A special directive for including a matplotlib plot.

Given a path to a .py file:

- On HTML, will include a .png with a link to a high-res .png.

- On LaTeX, will include a .pdf

This directive supports all of the options of the `image` directive,
except for `target` (since plot will add its own target).

Additionally, if the :include-source: option is provided, the literal
source will be included inline, as well as a link to the source.
"""

This task took a lot longer than I expected, so I'm going to have to pause for a while. But here's a couple of notes for improvement if anyone wants to take it on:

1) Clicking on the image in HTML currently goes to a high-res PNG. It could instead go to a PDF, which personally I think is preferable, but I know some people are adamantly opposed to installing a PDF plugin in their browser.

2) This only works if the .py files live in users/figures. A more general solution might be to move the actual rendering of .png and .pdf plots (which currently occurs in users/figures/make.py) to the plot directive itself, and have them rendered even more on-the-fly than they are already. Then it could pull .py's from anywhere (such as mpl-examples) and put the resulting images in the correct place for sphinx to find them and add them to the build.

3) The CSS could be tweaked so the images don't get a thick border in HTML. Putting a magnifying glass in the corner would be cool if there's any CSS wizards out there. But that's an aesthetic consideration. People may like the border.

Cheers,
Mike

···

--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

2

I've committed some changes that should address all three of these
issues. The plot_directive now assumes you are giving it a pyplot
python file (stored in doc/pyplots) and will generate the savefigs at
doc build time. The paths are a bit hairy in these rest directives so
I decided it was easiest to force all the python files to live in this
dir, and we can revisit this later. I am not convinced it is a good
idea to point to external files anyway for the image generation (like
examples/something.py) since someone may unwittingly change this w/o
begin aware the docs are relying on it. I addressed 1 and 3 by not
making the image clickable, but rather putting links to the high res
png and pdf below it, and along with the src there too. For now I am
including a link to the src even if the src is not included, but if
there is a reason not to we can easily remove this.

There are a few TODOs in there where the code could be cleaner or I am
having some unexplained problems. I also updated Darren's section in
the devel guide.

JDH

···

On Fri, Jun 13, 2008 at 9:40 AM, Michael Droettboom <mdroe@...31...> wrote:

This task took a lot longer than I expected, so I'm going to have to
pause for a while. But here's a couple of notes for improvement if
anyone wants to take it on:

1) Clicking on the image in HTML currently goes to a high-res PNG. It
could instead go to a PDF, which personally I think is preferable, but I
know some people are adamantly opposed to installing a PDF plugin in
their browser.

2) This only works if the .py files live in users/figures. A more
general solution might be to move the actual rendering of .png and .pdf
plots (which currently occurs in users/figures/make.py) to the plot
directive itself, and have them rendered even more on-the-fly than they
are already. Then it could pull .py's from anywhere (such as
mpl-examples) and put the resulting images in the correct place for
sphinx to find them and add them to the build.

3) The CSS could be tweaked so the images don't get a thick border in
HTML. Putting a magnifying glass in the corner would be cool if there's
any CSS wizards out there. But that's an aesthetic consideration.
People may like the border.

3

> This task took a lot longer than I expected, so I'm going to have to
> pause for a while. But here's a couple of notes for improvement if
> anyone wants to take it on:
>
> 1) Clicking on the image in HTML currently goes to a high-res PNG. It
> could instead go to a PDF, which personally I think is preferable, but I
> know some people are adamantly opposed to installing a PDF plugin in
> their browser.

Its too bad internet explorer requires a plugin to handle SVG, we could do svg
for html and pdf for latex. Now that I think of it, maybe we should be
generating svg files, they can be an additional link, but the pngs are the
ones that get rendered on the main page. It will help advertise our diverse
output formats, and many users get a scalable format without having to load
up Adobe.

> 2) This only works if the .py files live in users/figures. A more
> general solution might be to move the actual rendering of .png and .pdf
> plots (which currently occurs in users/figures/make.py) to the plot
> directive itself, and have them rendered even more on-the-fly than they
> are already. Then it could pull .py's from anywhere (such as
> mpl-examples) and put the resulting images in the correct place for
> sphinx to find them and add them to the build.
>
> 3) The CSS could be tweaked so the images don't get a thick border in
> HTML. Putting a magnifying glass in the corner would be cool if there's
> any CSS wizards out there. But that's an aesthetic consideration.
> People may like the border.

I've committed some changes that should address all three of these
issues. The plot_directive now assumes you are giving it a pyplot
python file (stored in doc/pyplots) and will generate the savefigs at
doc build time. The paths are a bit hairy in these rest directives so
I decided it was easiest to force all the python files to live in this
dir, and we can revisit this later. I am not convinced it is a good
idea to point to external files anyway for the image generation (like
examples/something.py) since someone may unwittingly change this w/o
begin aware the docs are relying on it. I addressed 1 and 3 by not
making the image clickable, but rather putting links to the high res
png and pdf below it, and along with the src there too. For now I am
including a link to the src even if the src is not included, but if
there is a reason not to we can easily remove this.

I just deleted the static_figs directory from svn, and moved the contents into
pyplots. The generated figures were committed to svn as well, so they should
not be auto-generated. This way we can consistently use the nice plot
directive to include all of our figures. I think there should be no problems
with this transition, but if you see one, please let me know.

I updated the documentation guide to reflect the change.

Darren

···

On Friday 13 June 2008 01:22:24 pm John Hunter wrote:

On Fri, Jun 13, 2008 at 9:40 AM, Michael Droettboom <mdroe@...31...> wrote:

4

I love working with people who know what they are doing.

Thanks guys, for the htmlonly directive. I was able to use it to clean up a
few annoyances in the pdf document, like some badly formatted content at the
beginning of each part, and the hyperlink on the main page to download the
pdf document (see the sixth page (page 1) of
http://matplotlib.sourceforge.net/doc/Matplotlib.pdf, and compare with the
one in your build/latex after your next update).

Darren

···

On Friday 13 June 2008 04:20:38 pm Darren Dale wrote:

On Friday 13 June 2008 01:22:24 pm John Hunter wrote:
> On Fri, Jun 13, 2008 at 9:40 AM, Michael Droettboom <mdroe@...31...> wrote:
> > This task took a lot longer than I expected, so I'm going to have to
> > pause for a while. But here's a couple of notes for improvement if
> > anyone wants to take it on:
> >
> > 1) Clicking on the image in HTML currently goes to a high-res PNG. It
> > could instead go to a PDF, which personally I think is preferable, but
> > I know some people are adamantly opposed to installing a PDF plugin in
> > their browser.

Its too bad internet explorer requires a plugin to handle SVG, we could do
svg for html and pdf for latex. Now that I think of it, maybe we should be
generating svg files, they can be an additional link, but the pngs are the
ones that get rendered on the main page. It will help advertise our diverse
output formats, and many users get a scalable format without having to load
up Adobe.

> > 2) This only works if the .py files live in users/figures. A more
> > general solution might be to move the actual rendering of .png and .pdf
> > plots (which currently occurs in users/figures/make.py) to the plot
> > directive itself, and have them rendered even more on-the-fly than they
> > are already. Then it could pull .py's from anywhere (such as
> > mpl-examples) and put the resulting images in the correct place for
> > sphinx to find them and add them to the build.
> >
> > 3) The CSS could be tweaked so the images don't get a thick border in
> > HTML. Putting a magnifying glass in the corner would be cool if
> > there's any CSS wizards out there. But that's an aesthetic
> > consideration. People may like the border.
>
> I've committed some changes that should address all three of these
> issues. The plot_directive now assumes you are giving it a pyplot
> python file (stored in doc/pyplots) and will generate the savefigs at
> doc build time. The paths are a bit hairy in these rest directives so
> I decided it was easiest to force all the python files to live in this
> dir, and we can revisit this later. I am not convinced it is a good
> idea to point to external files anyway for the image generation (like
> examples/something.py) since someone may unwittingly change this w/o
> begin aware the docs are relying on it. I addressed 1 and 3 by not
> making the image clickable, but rather putting links to the high res
> png and pdf below it, and along with the src there too. For now I am
> including a link to the src even if the src is not included, but if
> there is a reason not to we can easily remove this.

I just deleted the static_figs directory from svn, and moved the contents
into pyplots. The generated figures were committed to svn as well, so they
should not be auto-generated. This way we can consistently use the nice
plot directive to include all of our figures. I think there should be no
problems with this transition, but if you see one, please let me know.

I updated the documentation guide to reflect the change.

Darren

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

--
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

darren.dale@...143...
office: (607) 255-3819
fax: (607) 255-9001
http://www.chess.cornell.edu

5

I think we can make it work, but there are some minor hurdles. It is
a little brittle in my view to include auto-generated PNGs alongside
svn pngs because it makes cleaning hard (we currently have the same
problem in the _static dir with the mathtext pngs). The other problem
is that when I went to implement your svg suggestion, which is a good
one (ditto for ps links), I bumped into some not implemented errors
since we don't have draw_tex for svg and some latex runtime problems
when I tried to build the ps since I don't have the right fonts. All
of this can be worked around, but it will take a little work. I have
to run now...

We could have a little extra meta data stored, tagging certain files
that should not be auto-generated for certain extensions....
Perhaps we should introduce a new plot directive option, much like
include-source, which could be used to suppress auto-gen, or exclude
certain targets.

.. plot:: tex_unicode_demo.py
   :include-source:
   :no-autogen:

.. plot:: tex_unicode_demo.py
   :include-source:
   :exclude-backends: svg, gdk

I'll ponder this over the weekend.

JDH

···

On Fri, Jun 13, 2008 at 3:20 PM, Darren Dale <darren.dale@...143...> wrote:

I just deleted the static_figs directory from svn, and moved the contents into
pyplots. The generated figures were committed to svn as well, so they should
not be auto-generated. This way we can consistently use the nice plot
directive to include all of our figures. I think there should be no problems
with this transition, but if you see one, please let me know.

6

> I just deleted the static_figs directory from svn, and moved the contents
> into pyplots. The generated figures were committed to svn as well, so
> they should not be auto-generated. This way we can consistently use the
> nice plot directive to include all of our figures. I think there should
> be no problems with this transition, but if you see one, please let me
> know.

I think we can make it work, but there are some minor hurdles. It is
a little brittle in my view to include auto-generated PNGs alongside
svn pngs because it makes cleaning hard (we currently have the same
problem in the _static dir with the mathtext pngs).

How often does cleaning need to be done? Can "svn up" be a part of the
cleaning process?

The other problem
is that when I went to implement your svg suggestion, which is a good
one (ditto for ps links), I bumped into some not implemented errors
since we don't have draw_tex for svg and some latex runtime problems
when I tried to build the ps since I don't have the right fonts. All
of this can be worked around, but it will take a little work. I have
to run now...

We could have a little extra meta data stored, tagging certain files
that should not be auto-generated for certain extensions....
Perhaps we should introduce a new plot directive option, much like
include-source, which could be used to suppress auto-gen, or exclude
certain targets.

.. plot:: tex_unicode_demo.py

   :include-source:
   :no-autogen:

.. plot:: tex_unicode_demo.py

   :include-source:
   :exclude-backends: svg, gdk

I'll ponder this over the weekend.

May I suggest a third alternative, :exclude-formats: instead of backends.

Darren

···

On Friday 13 June 2008 9:54:58 pm you wrote:

On Fri, Jun 13, 2008 at 3:20 PM, Darren Dale <darren.dale@...143...> wrote:

7

This probably isn't the "real" solution, but I've been using svn-clean to clean my doc directory. Though I agree with John, we should have a clear demarkation between svn content and generated content.

Cheers,
Mike

Darren Dale wrote:

···

On Friday 13 June 2008 9:54:58 pm you wrote:
  

On Fri, Jun 13, 2008 at 3:20 PM, Darren Dale <darren.dale@...143...> >> > wrote:
  

I just deleted the static_figs directory from svn, and moved the contents
into pyplots. The generated figures were committed to svn as well, so
they should not be auto-generated. This way we can consistently use the
nice plot directive to include all of our figures. I think there should
be no problems with this transition, but if you see one, please let me
know.
      

I think we can make it work, but there are some minor hurdles. It is
a little brittle in my view to include auto-generated PNGs alongside
svn pngs because it makes cleaning hard (we currently have the same
problem in the _static dir with the mathtext pngs).
    
How often does cleaning need to be done? Can "svn up" be a part of the cleaning process?

The other problem is that when I went to implement your svg suggestion, which is a good
one (ditto for ps links), I bumped into some not implemented errors
since we don't have draw_tex for svg and some latex runtime problems
when I tried to build the ps since I don't have the right fonts. All
of this can be worked around, but it will take a little work. I have
to run now...

We could have a little extra meta data stored, tagging certain files
that should not be auto-generated for certain extensions....
Perhaps we should introduce a new plot directive option, much like
include-source, which could be used to suppress auto-gen, or exclude
certain targets.

.. plot:: tex_unicode_demo.py

   :include-source:
   :no-autogen:

.. plot:: tex_unicode_demo.py

   :include-source:
   :exclude-backends: svg, gdk

I'll ponder this over the weekend.
    
May I suggest a third alternative, :exclude-formats: instead of backends.

Darren
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA