On Wed, Feb 18, 2009 at 5:57 PM, Rodolfo S. Carvalho <[email protected]> wrote: > On Wed, Feb 18, 2009 at 5:51 PM, Adriano Marques <[email protected]> wrote: >> Hello Folks, >> >> Bartosz you've got a good point, but I think this is an easy topic >> that may avoid us some headache in the future if we see that our >> approach wasn't good enough and we have to move from one technology to >> the other. Also, it is nice to claim a pattern on our web site and ask >> every developer and newcomer to adopt that standard while documenting >> anything inside the organization. >> >>> I never worked in sphinx but I took a little time now, >>> just to know what it is. >>> Well, both of them, doxygen and sphinx look to be good, >>> my "Pro" to doxygen is that the documentation will be wrinten >>> in coments inside the code and this will help new contributors (like me) >>> to understand the code. >> >> That's an important point. Is it possible to do the same with sphrinx, >> Rodolfo? >> > > Yes, and IMHO it does it better then doxygen, because you don't need > to worry about document formatting inside the source code.
Except if you have some weird way to document things which breaks the restructuredtext format since sphinx expects docstrings to be in conformance with restructuredtext. > and you > also have a chance to highlight chunks of python code inside the docs, > using doctest notation. > Let me say that I hate seeing doctests mixed in docstrings, I hope umit doesn't follow that route, it is just too much noise to be together with .py files. Using doctest is fine, as long as they stay separated from the code. Just taking docstrings from the code and accepting that as documentation is bad, I wouldn't want to fix docstrings in the code to fix the documentation, I would want to just fix the documentation. This is a longer route to provide developer api, sure, but much better. > I think sphinx is more "pythonic", and also I defend it for being the > official doc format for python since version 2.6. > I prefer sphinx over doxygen too. But if we are going to just extract docstrings from the code and say that is our developer api, we could just use epydoc. For user documentation we could use sphinx then. >> >> Kind Regards, >> >> -- >> Adriano Monteiro Marques >> >> http://adriano-marques.blogspot.com >> http://www.umitproject.org >> http://www.pythonbenelux.org >> >> "Don't stay in bed, unless you can make money in bed." - George Burns >> > > > Cheers! > -- > Rodolfo Carvalho > Web Developer > [email protected] > -- -- Guilherme H. Polo Goncalves ------------------------------------------------------------------------------ Open Source Business Conference (OSBC), March 24-25, 2009, San Francisco, CA -OSBC tackles the biggest issue in open source: Open Sourcing the Enterprise -Strategies to boost innovation and cut costs with open source participation -Receive a $600 discount off the registration fee with the source code: SFAD http://p.sf.net/sfu/XcvMzF8H _______________________________________________ Umit-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/umit-devel
