"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): -------------------- snip snip -------------------- def font_from_name(psfontname): # ... # the general solution... gross! for name in ['font_from_name', '__doc__']: setattr(__, name, vars()[name]) -------------------- snip snip -------------------- So I place the one __init__.py function, and __init__'s __doc__ into the package. I think this makes more sense than using a __doc__.py file since I personally can't see any reason why __init__.py's docstring wouldn't be the package's docstring. 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. -Barry _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________