jan: thuban/Doc README,NONE,1.1

[Bernhard Reiter]

On Thu, Sep 23, 2004 at 12:33:49AM +0200, cvs at intevation.de wrote:
> Update of /thubanrepository/thuban/Doc
> In directory doto:/tmp/cvs-serv4024
> 
> Added Files:
> 	README 
> Log Message:
> Some info about how to generate technical documentation
> from the source code.
> This text was send to the Thuban developer mailing list on
> September 21st 2004 by Bernhard Reiter.

I'll appreciate the check-in of my pydoc hint,
note that the comment below are just my current state
of evalutating documentation tools.

Most of them make a difference to pydoc, because they 
can use a markup language to format the contents of the docstrings
(or in case of happydoc probably also the comments).
So they do not provide much extra information, unless
the Thuban developers decide for a docstring markup and one of those
tools. For me this would be a decision between reStructured text
and epydoc's markup language.

Expect for a bit of different presentation and display of comments
by happydoc, there is not much benefit over pydoc from the others.


> A brief look into other documentation tools
> resulted in that the the best overview about them was coming with
> epydoc at:
> http://epydoc.sourceforge.net/relatedprojects.html
> 
> epydoc seems to be very solid, because the author did a lot
> of reseach and decided for a very simple markup language.
> It might be surpased one day by docutils which use the more
> complicated reStructured text as markup.
> 
> As nice side contender is happydoc, because it does not import
> the python modules.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.intevation.de/pipermail/thuban-devel/attachments/20040923/c28f1970/attachment.bin