Re: reStructuredText (was: RE: [PEAR-DEV] Net_SMTP user's guide)

On Wed, Jun 11, 2003 at 10:45:31PM +0200, Pierre-Alain Joye wrote: > You may look again at phpDocumentor. You will see there is something > about general documentations and not inline docs. Using only it allows > us to make link from the inline docs to outline > documentations/tutorials. [...] > So, indeed we can use again another external non php tools, this time > in python *sigh*. However why not give a kick to phpdocument and help > Greg and Joshua to integrate it in a good manner in PEAR? I think we all believe that phpDocumentor is great for building API documentation from source code. It's an excellent tool overall, and its flexibility is very impressive. However, while phpDocumentor knows how to link to and include external documentation in its generated output, it doesn't appear to implement any kind of advanced markup for those external files. In other words, it looks like it just includes the (raw) text inside of its templated output. I don't have time to verify this right now, so please correct me if I'm wrong. I like the reStructuredText markup format because it's easy to learn and is very readable. The fact that the rendering tool that I'm using is written in Python is entirely incidental. I'm advocating the use of the reST format, not necessarily the docutils system (although it is well-implemented, does everything we need and is freely available). So if someone were to implement a reST parser for phpDocumentor, I think everyone would be happy. I don't intend to do this because I already have a set of tools for rendering reST documents in formats acceptable for use by PEAR users, and I don't believe in reinventing the wheel. See http://docutils.sourceforge.net/rst.html for details on reST. -- Jon Parise (jon@php.net) :: The PHP Project (http://www.php.net/)