[Tutor] docutils--what is the status?

[Paul Tremblay]

Someone on this mailing list suggested that the best way to include
documentation within a script or module was by using ReStructrued text.
I downloaded the docutils and have looked at a few examples and seem to
pretty much understand it.

That is, I understand how to create standalone documents and use
docutils to create XML of XHTML. However, the FAQ.txt states that the
utility to generate XML or XHTML from a script is not yet implemented:

     It supports multiple types of input, such as standalone files
     (implemented), inline documentation from Python modules and
     packages (under development), `PEPs (Python Enhancement
     Proposals)`_ (implemented), and others as discovered.

So if I am understanding things right, there is no way to type a command
and get a document for a script. For example, in perl, you can type 

perldoc script.pl

and see a complete list of information about the script in manpage
format.

Am I reading things right? It would be easy to create my own simple
script to extract all the text before the first and second tripple
quotes, output this to a file, and then run ReStructured text.

That would be kind of a hack--good for my use, but still not providing
python users with a sure way to get good documentation about a script.

(Just having the tool to create a nice format does not insure that the
programmer actually wrote good documentation--one of the most important
elements to whether a module is usable, in my opinion.)  

I like the idea of ReStructured text and will use it in my scripts. I
suppose it is a matter of time before the full implementation comes out.

Paul

-- 

************************
*Paul Tremblay         *
*phthenry@earthlink.net*
************************