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

[Barry A. Warsaw]

>>>>> "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
_______________