Sunday, October 26, 2008

docpicture: working ... and a query.

docpicture (see previous posts) is now working as a full prototype. By this, I mean that instead of doing

>>> help(some_object)

at the Python prompt, one can do

>>> from docpicture import view
>>> view(some_object)

and some_object's docstring will be displayed in your webbrowser, with any docpicture directive being translated so as to embed a nice picture. Well, by "any", I mean any turtle directive conforming to the limited syntax I have included.

When I compare the output of help() with that of docpicture.view(), I am struck at how much more information than simply the object's docstring is included. I have tried (briefly) to play with the pydoc module to see if I could redirect the output of help() to a string that I could process with docpicture.view() ... but to no avail.

If anyone knows how I could do this simply, I would be very grateful.

docpicture is going to be released (version 0.1) as soon as I complete a decent "readme" file.

--UPDATE-- Ok, after playing some more with pydoc, I found out how to do this.

In my module, I do the following:

import pydoc
from StringIO import StringIO
my_stdin = StringIO()
def my_pager(text):
my_stdin.write(pydoc.plain(text))
return
pydoc.pager = my_pager

pydoc.help(obj)
retrieved = my_stdin.getvalue()
my_stdin.close()

and use the retrieved text as I wish.

7 comments:

Anonymous said...

help() uses pydoc to generate its output. It's in the standard library.

Unknown said...

Except for the "Help on ... in module ...:" part, pydoc.TextDoc.document is doing exactly what you're looking for. You'd need to replicate the logic of pydoc.plain if you want boldface removed, though:

re.sub('.\b', '', pydoc.TextDoc().document(obj))

André Roberge said...

@Robert: Yes, I got that. I also found out that doing as I wrote in the update disables the normal help. So it's a simple matter of temporarily re-assign pydoc.pager and pydoc.TextDoc.bold, retrieving the value, and re-assigning it back.

Easy! I love Python! :-)

Anonymous said...

I come back with the aafigure suggestion; I rendered the README and putted it on my own website: http://www.oleastre.be/export/aafigure/README.html

That said, it's a really different approach than yours.

André Roberge said...

oleastre: This is really neat!. It is not really that different from what I want to do. In fact, it could probably be adapted/included in the approach I have been using. One main difference is that your images are separate svg files whereas I include mine as inline definitions.

You can have a look at a page that was generated dynamically by my program:

http://andre.roberge.googlepages.com/turtle_test.xhtml

I need to change the syntax for the drawing a bit (there's no need to specify something like "-> turtle(10)"; the second turtle declaration is redundant).

I'll try to look at your code later this week - assuming I can find it in the docutils sandbox. If you want to have a peak at my code (such as it is at the moment), feel free to send me an email. andre dot roberge at gmail dot com

Anonymous said...

Please, do not misattribute the code, it's not mine, it's original creator is Chris Liechti.

I just used aafigure it in a project for some docs, I was impressed by this small tool and wanted to let you know about it.

Alas, it needs some love, and does not work out of the box with recent releases of docutils (do not support directives declaration as classes)

this aafigure project needs some love, but your approach seems also interesting.

I hope I will have some time soon to have a look at both...

André Roberge said...

@oleastre: I sent an email to Chris Liechti thinking it was you.

I do plan to try and integrate a version of aafigure inside docpicture. Feel free to email me directly if you wish to pursue this conversation.