[Python-Dev] Documentation Tools

[Ka-Ping Yee]

On Fri, 16 Feb 2001, Tim Peters wrote:
> [Moshe Zadka]
> > We had a DevDay, we have a sig, we have a PEP. None of this
> > seems to help --
> 
> [Ka-Ping Yee]
> > What are you talking about?  There is an implementation and it works.
> 
> There are many implementations "that work".  But we haven't picked one.
> What's the standard markup for Python docstrings?  There isn't!  That's what
> he's talking about.

That's exactly the point i'm trying to make.  There isn't any markup
format enforced by pydoc, precisely because it isn't worth the strife.
Moshe seemed to imply that the set of deployable documentation tools
was empty, and i take issue with that.  His post also had an tone of
hopelessness about the topic that i wanted to counter immediately.

The fact that pydoc doesn't have a way to italicize doesn't make it a
non-solution -- it's a perfectly acceptable solution!  Fancy formatting
features can come later.

> This is especially bizarre because it's been clear for *years* that some
> variant of structured text would win in the end, but nobody playing the game
> likes all the details of anyone else's set of (IMO, all overly elaborate)
> conventions, so the situation for users is no better now than it was the day
> docstrings were added.
> 
> Tibs's latest (and ongoing) attempt to reach a consensus can be found here:
> 
>     http://www.tibsnjoan.demon.co.uk/docutils/STpy.html
> 
> The status of its implementation here:
> 
>     http://www.tibsnjoan.demon.co.uk/docutils/status.html
> 
> Not close yet.

The design and implementation of a standard structured text syntax
is emphatically *not* a prerequisite for a useful documentation tool.

I agree that it may be nice, and i certainly applaud Tony's efforts,
but we should not wait for it.


-- ?!ng