[Doc-SIG] Status of "structured text"

[M.-A. Lemburg]

Mike F Miller wrote:
> 
> I'm currently working on writing a medium sized tool that needs good
> embedded documentation, both for producing 'external' documents and
> for producing `-help` docs. I'd like to use the same string for both
> and have it formatted decently. For example, I'm thinking that having
> the ability to do something like...
> 
> if __name__ == '__main__':
>     """
>     This program runs a mpv test. The following options are available:
>       (list the options, blah, blah, link, blah)
>     """
>     help_re    = re.compile("\-h(elp)?")
>     for arg in sys.argv[1:]:
>         if help_re.match(sys.argv[i]):
>             print prettyparser(__doc__) # might be wrong syntax...

This would work if you'd put the above code into a main()
function.
 
> Would be a really good thing. Of course this implies a python
> prettyparser module of some kind. I was thinking that something like
> it might exist to parse the structured text format, or will eventually
> need to exist to support the SIGs goals...
> 
> Any thoughts or comments? Am I nuts, or should I try and write a
> structured text reformatter? Or a html->txt converter and use html
> instead?

There are many tools out there: gendoc, doc.py (see my Python Pages)
py2html.py (dito), py2pdf.py, etc...

A nice introspection tool is Ping's inspect.py (I think it was
called). As for text formatting, you could use some of the
APIs available in hack.py (PPs).

-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/