[Doc-SIG] PEP-0216

[Tony J Ibbs (Tibs)]

(Even if Jim and Ken can't contribute other than by listening, I personally
still feel knowing they're there is a Good Thing.)

Jim Fulton wrote:
> I took the liberty of creating a page in the StructuredText Wiki:
> http://dev.zope.org/Members/jim/StructuredTextWiki/DocumentationStrings
>
> to collect ideas for and comments on using StructuredText for
> doc strings.
>
> I'd appreciate it if people could add proposals and comments
> there. It's a Wiki page, meaning it can be edited through the
> web. To make changes, you need to be logged in to zope.org.
> Membership on zope.org is free. The editing format is, of
> course, StructuredText. :)

Well, I've just used my Zope membership (knew it would be useful one day) to
flesh out a little the pages

	http://dev.zope.org/Members/jim/StructuredTextWiki/DocumentationStrings

http://dev.zope.org/Members/jim/StructuredTextWiki/MosheZadkasProblemsWithSt
ructuredText

(those are *bound* to wrap).

I think for sanity at *this* end we need to conduct our conversation in
parallel - I'll make sure that significant material I produce gets placed
within the Wiki as I can, or at least referenced from there (as a non-Wiki
user, please realise that it takes *time* to get to grips with the
paradigms, and that's not something I have much to spare - the nonlinearity
of the medium can be a significant problem if one is in a hurry! and the
urge to fill in needless links is one I ...just...can't...resist...<snap>).

Personally, I would like to think we'll end up with:

* StructuredTextNG, provided by Digicool/Zope

* StructuredText??, a subclass of the above, containing extensions needed
for Python Doc strings (from what I've seen of the *documentation* of
StructuredTextNG, this is how one is *meant* to do things).

* A single BDFL-approved tool for producing documentation from Python
modules, using the Zope StructuredText.py module (subclassed as appropriate,
of course), included in the Python distribution.

* Possible feedback from the DOC sig into the development of
StructuredTextNG, via the "normal" methods for such things (whatever they
may be) - having the BDFL and his cohorts at Digicool can't but help with
our learning how to do this sort of thing. Note that this clause means we
don't have to get everything we want into StructuredText at the first go...

* As many *other* tools as people want to provide, just as normal, which
parse faster, or produce more output formats, or do other clever things -
after all, there's more than one way to do things (umm, no,
rewind that, something's wrong there...)

The question is, can we have it by Python 2.1 (hmm, first beta February
2001, final release March 2001 - let's go for it!)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
(hmm - Zope - better have a Zope compatible quote)
ZODB - "Nyah! Nyah! *My* variables last longer than *your* variables."
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)