Online doc generator (Was: Re: [PEAR-DEV] Amsterdam meeting agenda)

<mj@php.net> wrote : > On Sat Apr 10, 2004 at 11:1013AM +0200, Bertrand Mansion wrote: >> - Online documentation system >> I am thinking about some sort of automatic inline doc extractor that would >> create the API documentation, using PHPDocumentor, and add it to PEARDoc >> automatically. All this would be done on PEAR web. The process will be the >> same as with the new release upload. Actually, it could even be made at the >> same time. > > We have been discussing about this on the documentation mailing list > some time ago. Back then we came to the conclusion that it is wise > to *not* merge the documentation from PHPDocumentor into the manual, > because it would then take literally days to build it. Instead we might > provide automatically generated API documentation separately from the > "main" documentation. I don't have a problem with that but it probably requires to think about how you want to organize the information on the website. Especially, how API doc will be separated from/related to tutorials. The fact that it takes days to build the PEAR documentation looks like an evidence that the format chosen (docbook to name it) is not appropriate. Hopefully, all packages don't have documentation, otherwise it would take weeks ! >> I think we also need some sort of CMS for the documentation system so that >> we could easily add tutorials and class description. >> >> And the process should also be possible in the other way, I mean you provide >> your class and the API doc is copied from the PEAR site to your class. You >> get a fully commented and updated class back. >> >> The goal is to get rid as much as possible of Docbook, which is in my >> opinion the biggest mistake made by PEAR. I think we should also discuss the >> adoption of another format like reSt to replace it. > > I do not think we should drop Docbook. Instead I like the idea of > having a reST -> Docbook converter with which people can > semi-automatically convert their reST file into proper Docbook, which > will then be added to the manual. The Horde project has been starting > to develop a PHP-based reST parser, which I'm planning to use as well. Please tell me why we shouldn't drop docbook. In the suggested process, you add needless steps which will in turn add maintenance problems and inconstancies to the doc repository, not to say about the local copies. As usual, you will end up with fixed state documentation where changing just a typo takes 30 minutes + 1 week to appear publicly. Doesn't that look silly ?