From mikem@ichips.intel.com  Wed Sep  6 23:37:31 2000
From: mikem@ichips.intel.com (Mike F Miller)
Date: Wed, 06 Sep 2000 15:37:31 -0700
Subject: [Doc-SIG] Status of "structured text"
Message-ID: <200009062237.PAA19200@plxw0015.pdx.intel.com>

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...


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?

Thanks,

 - Mike



From gward@python.net  Thu Sep  7 03:59:43 2000
From: gward@python.net (Greg Ward)
Date: Wed, 6 Sep 2000 22:59:43 -0400
Subject: [Doc-SIG] Updated Distutils docs
Message-ID: <20000906225943.A1266@beelzebub>

Hi all --

I've been slowly plugging away at the "Distributing Python Modules"
manual over the last couple of days, and just uploaded the results to
python.org.  See

  http://www.python.org/sigs/distutils-sig/doc/

Especially the following sections of the "Distributing" manual:

  http://www.python.org/sigs/distutils-sig/doc/dist/describing-extensions.html
  http://www.python.org/sigs/distutils-sig/doc/dist/setup-config.html
  http://www.python.org/sigs/distutils-sig/doc/dist/source-dist.html
  http://www.python.org/sigs/distutils-sig/doc/dist/built-dist.html

The "Installing Python Modules" manual has also been updated from the
old copy that was on python.org, but this is mainly typo fixes (for
now).

Any feedback is welcome!

        Greg
-- 
Greg Ward                                      gward@python.net
http://starship.python.net/~gward/


From jhe@webde-ag.de  Thu Sep  7 10:08:56 2000
From: jhe@webde-ag.de (=?iso-8859-1?Q?J=FCrgen_Hermann?=)
Date: Thu, 7 Sep 2000 11:08:56 +0200
Subject: AW: [Doc-SIG] Status of "structured text"
Message-ID: <82C891B6DD60D411A6F200508BC5D60339C7AD@exchange1.cinetic.de>

-----Urspr=FCngliche Nachricht-----
Von: Mike F Miller [mailto:mikem@ichips.intel.com]
Gesendet: Donnerstag, 7. September 2000 00:38

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?
----

HappyDoc (see recent anncouncement on comp.lang.python) contains a
structured text module that parses such text and provides a class =
interface
to it. Have a look...

BTW, I think such a module should be part of Python 2.0 or 2.1 at =
least.

Bye, J=FCrgen


From mal@lemburg.com  Thu Sep  7 12:56:50 2000
From: mal@lemburg.com (M.-A. Lemburg)
Date: Thu, 07 Sep 2000 13:56:50 +0200
Subject: [Doc-SIG] Status of "structured text"
References: <200009062237.PAA19200@plxw0015.pdx.intel.com>
Message-ID: <39B78282.BB48E77@lemburg.com>

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/