How to create a docstring for a module?

[Tim Chase]

> * He hasn't actually defined a docstring. Docstrings have to be string 
> literals, you can't do this:
> 
> """%s does everything you could possibly want.""" % "xyz"

I've occasionally wanted something like this, and have found that 
it can be done by manually assigning to __doc__ (either at the 
module-level or classes) which can make some documentation bits a 
little easier:

   # ds.py ##############
   "original docstring"
   OPTIONS = {
     'FOO': 'bar',
     'BAZ': 'boing',
     }
   __doc__ = """
     This is %(FOO)s and it does %(BAZ)s
     """ % OPTIONS
   more_code_that_uses(OPTIONS)
   ######################


you can then

   >>> import ds
   >>> help(ds)
   ...

and see the formatted help that makes use of the options in the 
file.  Being lazy, I'm all for self-updating documentation ;-)

Even weirder is assigning a repr()/str()'able class-instance as 
the __doc__ for even crazier behaviors (though it looks like the 
internal help() function ignores them, perhaps requiring 
isinstance(__doc__, basestring) to pass)

   # ds2.py ###############
   class DynamicHelp:
     def __init__(self, name, count=0):
       self.name = name
       self.count = count
     def __str__(self):
       self.count += 1
       if self.count = 3:
         return "Are you REALLY that forgetful?!"
       return "%s:%i" % (self.name, self.count)
     def __repr__(self):
       return "<%s>" % self

   class C:
     "Raw C"
     def __init__(self, name):
       self.__doc__ = DynamicHelp(name)

where you can then do weird things like

   >>> import ds2
   >>> c = ds2.C("Hello")
   >>> c.__doc__
   <Hello:1>
   >>> c.__doc__
   <Hello:2>
   >>> c.__doc__
   Are you REALLY that forgetful?!
   >>> c.__doc__
   <Hello:4>

-tkc