Including EPS/PDF with automatic PNG conversion for HTML

[Alpha Zo]

Hello,

I just discovered Sphinx which I believe offers a great balance
between convenience and quality. I've used LyX on several important
projects but still have hard time to get other people to adopt it.

I noticed in the documentation that sphinx.ext.pngmath enables the
inclusion of mathematical notation via LaTeX markup with automatic PNG
rendering for HTML output.

There is a 2009 thread called "In what format should I maintain an
image". I have similar question. Can an EPS or PDF file be included in
a Sphinx document with PNG conversion for HTML output?

Thanks
Alphazo

[Roberto Alsina]

On Thursday 08 April 2010 09:34:42 Alpha Zo wrote:
> There is a 2009 thread called "In what format should I maintain an
> image". I have similar question. Can an EPS or PDF file be included in
> a Sphinx document with PNG conversion for HTML output?

If you have a EPS or PDF image it's trivial to add a rule in the Makefile to
convert them to PNG. If you have GNU make and ImageMagick installed, add this
at the beginning of your Makefile (assuming you have image1.pdf and
image2.pdf):

PNGIMAGES = image1.png \
image2.png

%.png: %.pdf
convert $< $@

Then change the html target to make it depend on the images:

html: ${PNGIMAGES}

And voila, the images will be converted from PDF to PNG whenever you build the
html target and they have changed.

[Alpha Zo]

Thanks for the tip. In fact I didn't realize that I could use the '..
image' command to include a PDF for Latex output (EPS doesn't work but
this is LaTeX related). That itself makes Sphinx even more powerful
because I can now do things à la LyX for including spreadsheets and
diagrams.

Coming back to your suggestion, I applied both modifications to both
Makefile. I see the conversion happening and a new PNG files being
generated. However when opening the HTML the PNG doesn't show up and I
see the text "_images/pos_market.pdf" instead of the picture. Please
note that in _build\html\_images there is no PNG, just the original
PDF file.

Thanks
Alphazo

[Roberto Alsina]

On Thursday 08 April 2010 11:08:04 Alpha Zo wrote:
> Thanks for the tip. In fact I didn't realize that I could use the '..
> image' command to include a PDF for Latex output (EPS doesn't work but
> this is LaTeX related). That itself makes Sphinx even more powerful
> because I can now do things à la LyX for including spreadsheets and
> diagrams.
>
> Coming back to your suggestion, I applied both modifications to both
> Makefile. I see the conversion happening and a new PNG files being
> generated. However when opening the HTML the PNG doesn't show up and I
> see the text "_images/pos_market.pdf" instead of the picture. Please
> note that in _build\html\_images there is no PNG, just the original
> PDF file.

Well, since I have no clue what your file layout is, you will have to take
care of the details yourself ;-)

Some tips:

1) You can use pos_market.* as the image name and sphinx will use the right
one (PNG for HTML, EPS for LaTeX, I think?)

2) If the PNG image is created, where is it? Change the Makefile so it's
created in the right place where the HTML link works.

[Alpha Zo]

COOL! It works now. By just replacing pos_market.pdf by pos_maket.*
and using your tip, the PNG has been automatically generated and
placed into the right _build\html\_images while Latex output uses the
original PDF figure.

This is official now, I'm switching to Sphinx ;) and I've already
started converting other fellows at my workplace for technical
documentations (not Python related though).

Again, thank you very much your valuable support.

Alphazo

[Roberto Alsina]

On Thursday 08 April 2010 11:37:18 Alpha Zo wrote:
> COOL! It works now. By just replacing pos_market.pdf by pos_maket.*
> and using your tip, the PNG has been automatically generated and
> placed into the right _build\html\_images while Latex output uses the
> original PDF figure.
>
> This is official now, I'm switching to Sphinx ;) and I've already
> started converting other fellows at my workplace for technical
> documentations (not Python related though).
>
> Again, thank you very much your valuable support.

Ok, now I have to convince you to use rst2pdf instead of latex and I'm done
for the day ;-)

[Alpha Zo]

Hi Roberto,

Any compelling reason to use rst2pdf over LaTeX? The rst2pdf version
of Sphinx manual found on the homepage looks much less attractive
(from a typographic standpoint) than its counterpart created with
LaTeX. If there are advantages I would be please to hear.

[Roberto Alsina]

On Thursday 08 April 2010 11:55:31 Alpha Zo wrote:
> Hi Roberto,
>
> Any compelling reason to use rst2pdf over LaTeX? The rst2pdf version
> of Sphinx manual found on the homepage looks much less attractive
> (from a typographic standpoint) than its counterpart created with
> LaTeX. If there are advantages I would be please to hear.

1) It needs about 620MB [1] less of software to be installed
2) The output is much easier to customize than LaTeX's (you can
change your headings fonts to any TTF with a two-line stylesheet)
3) You can make it do more stuff without becoming a LaTeX guru first.

Some people do prefer the LaTeX output. Some others find it a bit old
fashioned.

[1] That's what the "recommended" texlive install amounts to in my
linux box.