«

This seems to tie in with a few other things that have been posted
recently...

One of the things I'm currently working on is something I call pk,
a layer on top of Tkinter which gives a much more object-oriented
inteface to Tk. This is relatively complex, and one of the things
I'm missing is the lack of good doctools support in Python.
Something like Javadoc would be nice. Something like d'oxygen
would be even nicer.

Both of those depend on a "documentation markup language", which
is something Python doesn't have, and which is a pain to define
and implement. But, Python can easily define such a markup
language, it would seem, simply by defining appropriate functions.
So, I spent a few hours today writing a page or so of code,
and came up with a little library which, used in the
following way:


from doct import *
t = "To be or not to be; that is the question."
print doct(
dsection("Section", t, titleunderline="="),
dargs(arg1="This is argument 1, with a long
description", arg2="Second arg.")
)

(doct is both the module name, and the name of a function) prints out this:

Section
=======
To be or not
to be; that
is the question.

ARGUMENTS
---------
arg1: This is argument
1, with a long
description

arg2: Second arg.


(The lines are short because I was testing wrapping and
didn't want to type in too much test text.)

Doing this has convinced me of a number of things:

1) It'd be very easy to get a useful doct library up and
running quickly.

2) Generators greatly ease the writing of this sort of
thing, and make it much more efficient. (Well, I only
suspect the latter, but it's a suspicion that's easy
to justify.)

3) Using Python to write Python documentation is a
big plus, because a Python-oriented editor typically
is set up in such a way that it aids in the viewing
of the documentation as it is written. (For example,
my editor is set to bold function apps, and display
strings in green; so in the example given, the
structure of the document is clearly visible just by
looking at the bold elements and, of course, by indenting.)
The only minus is that
one types perhaps more quotes/parens/commas than would
be desirable, but I found that to be an annoyance
that was greatly outweighed by being so easily able
to work with the structure of the document.

4) This could be used to generate multiple types
of output. I don't think it would be much more work
to support, say HTML output.


The biggest annoyance is the fact that this would
not have any support such as enjoyed by docstrings,
so instead of saying something like:

def foo(x):
'''docs'''
pass

one would have to say something like

def foo(x):
pass

foo._doct_ = doct('''docs''')

This is more of a drawback than it might seem; in longer
functions/classes, the documentation is no longer near the
start of the function/class.

I'd appreciate it if people could comment on what they
think of such an approach. If there is any interest,
perhaps we could define a basic set of documentation
functions and implement them, and then see what happens
from there.

Thanks,
Ken McDonald

On Thu, May 06, 2004 at 02:12:26AM +0000, Kenneth McDonald wrote:
> This seems to tie in with a few other things that have been posted
> recently...
>
> One of the things I'm currently working on is something I call pk,
> a layer on top of Tkinter which gives a much more object-oriented
> inteface to Tk. This is relatively complex, and one of the things
> I'm missing is the lack of good doctools support in Python.
> Something like Javadoc would be nice. Something like d'oxygen
> would be even nicer.

Have you seen epydoc <http://epydoc.sf.net>?

-Andrew.

In article <> ,
Kenneth McDonald <> wrote:
>
>Both of those depend on a "documentation markup language", which
>is something Python doesn't have, and which is a pain to define
>and implement. But, Python can easily define such a markup
>language, it would seem, simply by defining appropriate functions.

http://docutils.sourceforge.net/

Not quite ready for prime time in terms of embedded Python docs, but
it's getting there.
--
Aahz () <*> http://www.pythoncraft.com/

Adopt A Process -- stop killing all your children!