A Divendres 13 Abril 2007 14:25, Dieter escrigué: > 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?
As Ivan already said, we have right now two worlds in PyTables doc formats: ReST for docstrings and Docbook for the User's Guide. It would be really nice to have a gateway that can unify both worlds, but this currently seems more a dream than anything. One possibility would be to renounce to have a 'Library Reference' in the PyTables User's Guide and generate the reference just using Epydoc (for example), but I think this would make the User's Guide far less useful, and will force users to have a couple of documents to have the complete documentation. In addition, Docbook allows for very good rendering for paper output, and I'm afraid that Epydoc don't. Mainly because of this, I think that we are not going to drop the 'Library Reference' from User's Guide, as I feel that having both tied together in one single document has a high value for users. So, I'm afraid that we will have to manually synchronize the docstrings in ReST and the Docbook for a long time yet. So, I'm not sure whether it is worth the effort to spend time processing the docstrings with Epydoc (at least, without solving first the issues that I've mentionen above). But, in any case, it would be a nice thing to look at the results (and who knows, perhaps we can see the way to integrate the ReST and Docbook worlds in the future). Cheers, -- >0,0< Francesc Altet http://www.carabos.com/ V V Cárabos Coop. V. Enjoy Data "-" ------------------------------------------------------------------------- Take Surveys. Earn Cash. Influence the Future of IT Join SourceForge.net's Techsay panel and you'll get the chance to share your opinions on IT & business topics through brief surveys-and earn cash http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV _______________________________________________ Pytables-users mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/pytables-users
