[Doc-SIG] Docstring markup process

[Ka-Ping Yee]

On Mon, 12 Mar 2001, Tony J Ibbs (Tibs) wrote:
> I *know* life can't be that simple, as I'm sure some of the existing
> PEPs have started on other lists. So what is the situation? Does one
> just put something together and send it to Barry Warsaw with some
> plausible excuse?

Pretty much, yes.  If you're serious enough about a proposal to write
a PEP for it, and it's clear that the goals are at least reasonable,
it should be easy to ask Barry to assign you a PEP number.  Or if the
process has to be formalized, i'm sure one of us will be happy to vouch
for any docstring proposal that looks reasonable and to submit it on
the author's behalf.

> Ka-Ping - are you proposing anyone in particular to start a PEP for
> usage of ST<whatever> in docstrings,

No.  Indeed, i think the whole point of Paul's suggestion was to remove
the expectation that we would somehow all *first* agree on something and
then delegate someone to do the work of describing it in a PEP; rather,
the onus is now on whoever wants to champion a proposal.

> Suggestion for meat-and-bones of PEP:
>
> 1. STNG plus '>>>' plus '#...#', maybe plus "tagged paragraphs" [...]
> 2. Future enhancements to include: <list of future enhancements> [...]
> 3. Whether ST<whatever> gets vastly expanded [...]

So don't think of it as "the PEP".  Write *your* PEP and do the best
you can to cover the bases.  You can address things like "the library
reference docs should be moved into the module docstrings for the
following reasons, and this is how we would do it" or "the library
reference docs should not be moved for the following reasons..." etc.

So yes, please write!


-- ?!ng

"Computers are useless.  They can only give you answers."
    -- Pablo Picasso