On 17/10/2008 23:10, Dirk Meyer said the following: > First draft, patches with ports from the wiki doc to Sphinx welcome. > http://www.sachmittel.de/kaa/
After a san disk failure at work I had all day to do some documenting with Sphinx. After this I think the output looks very nice but it does have some real problems. The purpose is to generate documentation about the program code and it's interfaces. Sphinx seems to split the documentation into two parts, some in the code with reST comments and some out of the code in separate rst files. IMHO this is bad, it's hard enough to update the documentation for a function when the function is there in front of your eyes. The idea of having to open a separate file to update the documentation is just not going to happen. Another problem with it is does not generate a source listing and link the documentation to the code. The show source link shows the rst source file. The :auto*: stuff doesn't always work very well. :autoclass ClassName: does not show the documentation for the __init__ function. Default values can be expanded, try: | def function(environment=os.environ): | pass Sorry to be a bit negative about Sphinx, I don't think it is that much better than epydoc or doxygen. Duncan ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Freevo-devel mailing list Freevo-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/freevo-devel
