Re: [PYTHON DOC-SIG] Templatising gendoc, and more.
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 _______________
"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 _______________
On Tue, 4 Mar 1997, Barry A. Warsaw wrote:
"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!
If i'm tracking what the actual issue is here (making the contents of a package's __init__ module also be the contents of the package module itself?), then (1) i'm for it - it was actually part of my original design, and the prototype implementation, and (2) i am hoping to play with ni sometime soon, experimenting with making the __init__ module and the package module one and the same (in sys.modules), so the contents are intrinsically the same. (I am also hoping to take my first foray into profiling python, to explore prospects for optimizing ni.) Soon.
[...] 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.
This will be the case if the two objects are actually one. For free! (In fact, the reduction of a module object makes for underhead, rather than over:-) We'll have to see if that'll work, though. Ken _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
participants (3)
-
Barry A. Warsaw -
Ken Manheimer -
Mark Hammond