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

Discussion in 'Python' started by Kenneth McDonald, May 6, 2004.

  1. 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
     
    Kenneth McDonald, May 6, 2004
    #1
    1. Advertising

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

    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.
     
    Andrew Bennetts, May 6, 2004
    #2
    1. Advertising

  3. Kenneth McDonald

    Aahz Guest

    In article <.2wire.net>,
    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!
     
    Aahz, May 6, 2004
    #3
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Nik Coughlin
    Replies:
    12
    Views:
    632
    Nik Coughlin
    Dec 1, 2005
  2. Replies:
    1
    Views:
    371
    bruno modulix
    May 10, 2005
  3. dice
    Replies:
    2
    Views:
    348
  4. mike_ni
    Replies:
    2
    Views:
    307
    Mr. SweatyFinger
    Mar 7, 2007
  5. Ron Provost
    Replies:
    0
    Views:
    388
    Ron Provost
    Mar 25, 2008
Loading...

Share This Page