On Thu, Feb 19, 2009 at 12:33 PM, Guilherme Polo <[email protected]> wrote: > 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.
Are we going to move to sphinx ? -- -- 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
