Tuesday, October 14, 2008

Viewing embedded pictures within docstrings

In a recent post on the Python mailing list, it was suggested that it would be useful if "small" pictures could be embedded within docstrings as additional information. As is often the case, many words were written ... but little code was produced. As I have been guilty of this myself in the past, I decided that it was time to do things differently. After a quick prototype sent to the Python list, I wrote this recipe which gives a simple way to embed and display images inside a docstring in a totally transparent way.

Is this something that people would find useful? Any suggestions for improvements? Should I implement this within Crunchy? (Btw, Crunchy 1.0 alpha 1 has been released just last week).

3 comments:

Paddy3118 said...

Whilst interested in getting richer content via help(), I most definitely DON'T want to pay the price of having bit-strings in the source!
It is very ugly, and unmaintainable. How do you catch an inadvertent edit to the image?

I would much rather you support xhtml for this and either use img tags to external image files. SVG would be better than embedded bitmaps.

- Paddy.

oleastre said...

Did you already had a look at the aafigure in the docutils sandbox ?

http://docutils.sourceforge.net/sandbox/aafigure

I used it for some projects documentations and it can be really usefull.

André said...

Paddy: I agree that it is not pretty; but the idea is to be able to distribute only one module and have everything in it. As for inadvertent edit; one way to prevent it might be to compute some information about the string (crc?) and include it in the source as well - and recompute it every time an image is displayed (using this as a means to detect errors).

Oleastre: This looks interesting ... but I can't see the result as the page says that the aafigure directive is unknown.