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

[Mark Hammond]

> Date:          Mon, 3 Mar 1997 11:16:34 -0500
> From:          "Barry A. Warsaw" <bwarsaw@anthem.cnri.reston.va.us>
> To:            MHammond@skippinet.com.au
> Cc:            doc-sig@python.org
> Subject:       Re: [PYTHON DOC-SIG] Templatising gendoc, and more.
> Reply-to:      "Barry A. Warsaw" <bwarsaw@CNRI.Reston.Va.US>

> 
> >>>>> "MH" == Mark Hammond <MHammond@skippinet.com.au> writes:
> 
>     MH> Couple of quick questions - how can a ni package provide doc
>     MH> strings?  Eg, a package named "xyz" is a directory, _not_ a
>     MH> file.  I added a convention to gendoc that a file called
>     MH> "__doc__" in a packages directory will be read, and treated as
>     MH> docstrings for the module itself (which makes lots of sense to
>     MH> me, as then you dont need to distribute it) Also, I "flatten"
>     MH> the "__init__" module, so that all docstrings and methods are
>     MH> documented in the package itself - ie, __init__ never gets a
>     MH> mention in the docs. Do these sound OK?
> 
> I think Ken M. was the first to champion flatting of __init__ into the
> package module.  The argument is that flattening is the most natural
> way to think about package modules and most package authors are going
> to want to this, so it makes sense to be the default behavior.  I even
> went so far as to add the couple of lines to ni.py to make this
> happen, but Guido nixed it, partially because there wasn't enough
> experience with ni.py to back-up the `most common usage' argument.
> 
> In any case, when I packagized some parts of Grail, I added the
> following gross hack (taken from fonts/__init__.py):

:-)  Ive come up with the same hacks, without ever seeing fonts :-)

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

> What I would to do ni, is automatically put any non-underscore
> prefixed symbol appearing in __init__.py into the package module's
> namespace.  I would also put __doc__ into that namespace.  It's all of
> a two or three line change to ni.py.  Also, you might provide some way
> of controlling what gets put into the package's namespace from
> __init__.py.

Im sure many people will dis-agree here, but IMO docstrings in the
code is cute, but on-line browsing of docstrings wont be used
anywhere near as much as generated documentation.  I think it most 
important docstrings be kept near the sources for maintenance, rather 
than browsing.
I'd ask if flattening of the doc strings at run-time is really worth 
it?

Another interesting "feature" of docstrings is that the sources
often get _twice_ as big (Python is partly to blame here, as the
programs themselves are often so small :-).  If you consider the
win32com stuff, not only are the sources twice as big, all the doc
strings are _also_ in the generated HTML.

And at run-time, obviously, they take more memory.  And the more 
keen you are with the documentation, the more penalty you pay. 
(OK - were not talking too much, and Im not really _that_ concerned, but...)

This is one reason why I like my new little __doc__ file convention.  
It means I can put "overview" type information in a seperate file 
that is included in the HTML build, but not part of the sources (but 
still very close).  Browsers wont see it, but people browsing wont be 
looking for "overview" information anyway - they are more likely to 
be looking for a specific object...

Mark.
----------------------------------------------------------------------
Mark Hammond - MHammond@skippinet.com.au 
Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc
<http://www.python.org> & <http://www.python.org/ftp/python/pythonwin>

_______________
DOC-SIG  - SIG for the Python Documentation Project

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