[DOC-SIG] doc strings could be in a variety of formats

[Edward Welbourne]

I said earlier that ...
> I'll come back (if I remember) to how we might be able to improve on
> this ...

Doc strings are principally important to the author of the python code
in which they appear.  Their secondary importance is that they can be
extracted by a uniform toolset (in python) into, at least, HTML.

Imagine a standard set of classes which describe a common form into
which our doc strings are to be parsed by the common toolset.  We can
write simple parsers from a few variants on the doc-string format into
this internal form.  If a module or class sets its __docform__ tag to an
object with a .parse(string) method, the tools crawling the namespace to
extract docs can notice this and use that __docform__ as the parser for
the doc strings in the module or class.  The onus of supporting a new
doc-string format falls on those who depart from the fold, but they get
the option if they're prepared to take that effort.

Does gendoc contain classes which represent the parsed strings ?  Does
it provide such a __docform__ object which might serve as the default ?

With this sort of setup, those of us who like HTML can write our doc
strings in HTML (provided we're willing to write ourselves a parser for
it) for use in place of the gendoc one: as for HTML, so for any of the
myriad of doc forms out there in the world.  Furthermore, it shouldn't
be <EM>too</EM> hard for someone fed up (in interactive sessions) with
decoding some other contributor's doc strings to write something which
turns the parsed doc-strings back into their own preferred format of
doc-strings for display (chose your own __str__ method for the object
produced by a __docform__).

With a scheme like this, we can have our cake and eat it.
Please, someone, tell me what I've missed ;^>

	Eddy.

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________