[Doc-SIG] going awry

[Tony J Ibbs (Tibs)]

M.-A. Lemburg wrote:
> Please let me get this straight: as far as I understood Guido's
> post, he only mentioned that rich text markup didn't work in out
> in his projects -- he never outruled rich text markup for general
> use, so I suspect all this confusion to be based on a
> misunderstanding.

Guido said:
> PS.  Don't spend too much time trying to make StructuredText or some
> variation thereof work.  In my experience with systems that use ST
> (like ZWiki), it sucks.  There basically are two options I like:
> nicely laid out plain text, or a real markup language like Latex or
> DocBook.

That seems to be a downer for anyone trying to produce a docstring
markup format.

Of course, I think he has been soured by one particular implementation
of something that wasn't what we were proposing (and given he seems to
like MoinMoin which has an even more ad-hoc approach to text and what it
"means", I don't *quite* understand why he's so down on even STClassic).

> Ideally, there should be an interface for extracting
> information from single doc-strings or maybe even modules which
> then lets everybody plug in their own favourite doc-string parser.
>
> We already have tons of different auto-doc tools out there in
> the Python universe -- the problem with most of them is that they
> do not allow for parser plugins. This should change, IMHO.

HappyDoc seems to be the leader here - I keep mentioning it partly
because it seems to be under active development, partly because the
author is (at least in principal) interested in the result of what we're
doing, and partly because it aims to use plugins for both parsing the
text and producing the output.

But there is a problem with *recognising* what markup is used in what
docstring, if there isn't one standard!

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)