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 ------------------------------------------------------------------------- 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 [email protected] https://lists.sourceforge.net/lists/listinfo/pytables-users
