[PYTHON DOC-SIG] Templatising gendoc, and more.

[Barry A. Warsaw]

>>>>> "MH" == Mark Hammond <MHammond@skippinet.com.au> writes:

    MH> Ive _always_ done this in __init__, and maybe we would find
    MH> that the "most common usage" argument is more pervasive now?

Indeed!

    MH> Im sure many people will dis-agree here, but IMO docstrings in
    MH> the code is cute, but on-line browsing of docstrings wont be
    MH> used anywhere near as much as generated documentation.

As opposed to Emacs Lisp docstrings, which is my first model for how
this stuff can be used.  There are many differences b/w Elisp
docstrings and Python docstring, but there are some similarities
(sorry for quoting out of order):
    
    MH> Another interesting "feature" of docstrings is that the
    MH> sources often get _twice_ as big

Elisp byte-compiled files suffer the same fate, which I why I only
docstring-ify functions intended as part of the public interface to a
package.  Otherwise, I use comments instead of docstrings (although
the actual content is very similar), or sometimes just don't include
text in that place in the code.

    MH> I think it most important docstrings be kept near the sources
    MH> for maintenance, rather than browsing. I'd ask if flattening
    MH> of the doc strings at run-time is really worth it?

I was probably not clear (or I'm misunderstanding).  I only put
sort-of meta-package documentation in __init__.py's docstring, and I
think it makes sense to flatten that into the package module's
namespace, since you are documenting the package.

But I agree that on-line browsing of the docstrings will probably
never be very widespread, until we get Pymacs/PTUI to replace all of
Our Favorite Editors.

:-)

-Barry

_______________
DOC-SIG  - SIG for the Python Documentation Project

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