Duncan Webb wrote: > 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.
You don't have to. Sphinx does not care. It looks like official Python doc is pure reST. But I do not want to write two docs and I like the doc in the source code. That is why I use the auto* code for most functions. > 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. I don't understand. Look at the beacon doc for example. It has some explaination text and after that a list of function with autodoc. If you fix the function doc you can re-generate the Sphinx doc. My idea is to use the py files for API doc (what does a function do) and the tutorial with examples in reST. > 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. Yes. But I don't think we need it. > The :auto*: stuff doesn't always work very well. :autoclass ClassName: > does not show the documentation for the __init__ function. You can configure that. class docstring or __init__ docstring. I prefer the class docstring as it is now. > Default values can be expanded, try: > | def function(environment=os.environ): > | pass Sphinx gives you a way to ignore the auto stuff for some functions. In the example above you can use the docstring in Sphinx but rewrite the function signature in reST. > Sorry to be a bit negative about Sphinx, I don't think it is that much > better than epydoc or doxygen. I disagree: - I can choose what functions Sphinx should doc and what to skip. - I can define the order of functions (there is epydoc groups, but it does not work that good) - I can mix API doc, tutorial and example code Yes, Sphinx is not perfect. But IMHO it is better. Dischi -- Evolution doesn't take prisoners ------------------------------------------------------------------------- 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
