[DOC-SIG] Re: [PSA MEMBERS] [XML] Notes on the Tutorial's markup

[raf]

>>A related issue is whether we intend to have both a library reference
>>and structured docstrings? Or is the library reference just what you get
>>by concatenating the docstrings from the various modules? Are people
>>willing to make the source the documentation source too?

>	In general I think docstrings and a reference manual are two
>different things.  The LibRef is supposed to be fairly complete, and
>may include sample code, stylistic comments ("You can override this
>method, but it's a bad idea; do this instead...").  Docstrings are
>intended to be displayed by class browsers and used as comments, and
>every byte in a docstring is dragged around at runtime, so you don't
>want them to get too bloated.  Making a LibRef out of docstrings will
>result in either huge docstrings, or a too-terse LibRef.  

>	This means we don't need to use XML/SGML markup in docstrings,
>and it isn't necessary that everything can be done in pure Python
>(though it would be nice, and probably better, IMHO, since you'd have
>to install less software).

Literate programming is essential, though, if you want any hope of the
documentation matching the implementation.

When python code is written, the docstrings must be there, but they could
be stripped out when 'installing' the module, just as the code is
'stripped out' when producing the documentation.

Perhaps each docstring could have a small component that is kept at run-time.

raf


_______________
DOC-SIG  - SIG for the Python Documentation Project

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