Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Python documentation: How about structured documentation? Looking for comments/suggestions

Reply
Thread Tools

Python documentation: How about structured documentation? Looking for comments/suggestions

 
 
Kenneth McDonald
Guest
Posts: n/a
 
      05-06-2004
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
 
Reply With Quote
 
 
 
 
Andrew Bennetts
Guest
Posts: n/a
 
      05-06-2004
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.


 
Reply With Quote
 
 
 
 
Aahz
Guest
Posts: n/a
 
      05-06-2004
In article <(E-Mail Removed).2wire.net> ,
Kenneth McDonald <(E-Mail Removed)> 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 ((E-Mail Removed)) <*> http://www.pythoncraft.com/

Adopt A Process -- stop killing all your children!
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Re: How include a large array? Edward A. Falk C Programming 1 04-04-2013 08:07 PM
Really badly structured Python Books. Andre P.S Duarte Python 4 04-16-2007 11:17 PM
Encrypt/Decrypt a structured file kevininstructor@state.or.us ASP .Net 1 09-25-2004 05:25 AM
Storing structured types in request Dharmesh ASP .Net 4 07-29-2004 04:51 PM
Using xml source in datagrid -- possible with non-structured data? KatB ASP .Net 3 10-29-2003 07:09 AM



Advertisments