On 4/16/07, Dieter <[EMAIL PROTECTED]> wrote: > On 4/13/07, Ivan Vilata i Balaguer <[EMAIL PROTECTED]> wrote: > > Dieter (el 2007-04-13 a les 08:25:34 -0400) va dir:: > > > > > On 4/13/07, Dieter <[EMAIL PROTECTED]> wrote: > > > > On 4/13/07, Dieter <[EMAIL PROTECTED]> wrote: > > > […] > > > > > How about considering an all in one framework like Doxygen. I really > > > > > liked using for my c and c++ code. I see it now accommodates python. > > > > > See the following: > > > > > > > > > > Home: > > > > > http://www.stack.nl/~dimitri/doxygen/ > > > > > Python Specific Article: > > > > > http://engtech.wordpress.com/2007/03/20/automatic_documentation_python_doxygen/ > > > > > External Extension: > > > > > http://code.foosel.net/doxypy > > > > > > > > > > > > > Another showing the markup syntax: > > > > http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks > > > > > > > > > > Epydoc was recently improved and seems to allow a nice amount of > > > flexibility in combination with the restructured text. Not to mention, > > > it supports all the features found in normal doxygen (except for the > > > built in search engine). > > > > > > I'm gonna go ahead and transfer the docs over. Any comments? > > > > What do you mean with that sentence? (Sorry, my English is not so > > good.) If you mean you're going to convert the docs to some of those > > formats, allow me to *strongly* disagree. In the first place, I'm not > > eager to start such an effort without adequately discussing the pros and > > cons of each proposal. Second, we're in the process of overhauling and > > synchronising docs for the 2.0 release, so it's not the best moment to > > do it. ;) And third, none of the proposals seem to be adequate for the > > PyTables docs, since we need a tool which supports both narrative and > > reference sections with cross-references between them (leaves Epydoc > > out, dont't know about Doxygen), with good browseable and printed > > output, and which supports introspection of docstrings (lots of classes > > in PyTables are dynamically generated, which leaves Doxygen out). > > > > You see, if it was as easy as that we wouldn't be keeping the docs in > > sync by hand! ;) > > > > Of course, you can do what you want with your own branch, but I still > > advise you to wait until the docs are settled for an easier work. > > No no, I would not have done anything without consensus from you guys. > I apologize for the mis-understanding. And your right, epydoc is far > from adequate. I took Francescs comments thoughtfully, and over the > weekend I did a lot of research. Doxygen is very flexible and *very* > nice. But, as you've described Ivan, and what I also envisioned, there > are some improvements to doxygen that would make our dreams of an > ideal documentation generator possible (as well as a developers > sophisticated architecture reference tool). > > That realization re-invigorated some pet-peeves I've had for a while > now. So, I'm gonna address this first. I'm starting a project called > smartFOSS which will not only specifically address our discussion > here... but also my pet-peeves regarding sw tools and how I would like > to use them. I feel this could also benefit the entire oss community > (as far as I can tell). > > So, I'm gonna get this project started first, with documentation > generation (and a developer's architecture reference feature) at the > top of the "features" todo list. But, I'll be around. I'm not going > anywhere. ;) I'm not looking at enabling the full project concept yet. > Just enough to make my life easier. > > If you care to see the projects mission statement: > https://launchpad.net/smartfoss > > -Dieter > Just to emphasize... Qt has what I consider to be a model of a nice document system. http://doc.trolltech.com/4.3/index.html
Now just throw in what doxygen can offer (graphs, search, extensive cross-reference, autogeneration)... and then some, and you'll see what I'm referring to and what I'd really like to see all project developers be able to provide to their users. I'll see what I can do :') -Dieter ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Pytables-users mailing list Pytables-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/pytables-users
