Home Original page

What's "the standard" for code docs?

Paul McGuire ptmcg at austin.rr.com
Wed Feb 20 03:32:38 EST 2008 
On Feb 15, 10:59 am, Preston  Landers <pland... at gmail.com> wrote:
> Hey guys and gals.  What are all the cool kids using these days to
> document their code?  My goal is to create in-line documentation of
> each package/module/class/method and create some semi-nice looking (or
> at least usable) packaged documentation from it, in HTML and/or PDF
> format.
>
> I've been using effbot's PythonDoc for a while, but it seems like "the
> new standard" (if there is one) is docutils and restructured text
> (ReST.)  Is that accurate?
>
> Just from glancing at some samples of ReST the actual format looks
> much easier to work with in "plain text" in the text editor.
> PythonDoc has not been very popular with my team due to its HTML-ish
> nature and I think ReST will gain more acceptance.  Of course I don't
> want to bother making the jump from PythonDoc to docutils if that
> project is somehow a dead end.
>
> thanks for any info or advice you can provide.
>
> Preston

I use epydoc for pyparsing, and I really like the results.  Just make
sure that importing your modules doesn't really do anything
substantial (like connect to db's, or run unit tests that run for
hours); epydoc imports your code and then introspects it to extract
the classes, methods, docstrings, etc.

(And I think you asked an honest question, and did not deserve the
rude answers you got.  This NG is normally better behaved.)

-- Paul
More information about the Python-list mailing list