[Doc-SIG] docstring grammar

[M.-A. Lemburg]

David Ascher wrote:
> 
> Proposed format for docstrings:
> ...
>   Is there value in having string interpolation?  David Arnold mentioned
> 
>        __version__ = "$Revision$[11:-2]
>        __date__ = "$Date$
> 
>     which raises some issues.  I don't think that having [11:-2]
>     evaluated by the docstring parser is a wise idea.  However, I can
>     imagine that the module author could do:
> 
>        __version__ = "$Revision$"[11:-2]
> 
>     in the Python code, and then
> 
>        Version:: %(__version__)s
> 
>     in the docstring and that such a simple string interpolation
>     mechanism could have value.  I'm not sure it's worth the
>     complication though.  What dictionary would be used to do the
>     interpolation?

This raises the question of whether to parse or evaluate the
loaded module. Evaluation has the benefit of providing "automatic"
context, i.e. the symbols defined in the global namespace
are exactly the ones relevant for class definitions, etc. It
probably makes contruction of interdepence graphs a lot easier
to write. On the downside you have unwanted side effects due to
loading different modules.

Some notes on the proposal:

· Mentioning the function/method signature is ok, but sometimes
  not needed since e.g. the byte code has enough information to
  deduce the signature from it. This is not true for builtin
  function which is probably the reason for all builtin doc
  strings to include the signature.

· I would extend the reference scheme to a lookup in the module
  globals in case the local one (in the Reference section) fails.
  You could then write e.g. "For details see the [string] module."
  and the doc tool would then generate some hyperlink to the
  string module provided the string module is loaded into the
  global namespace.

· Standard symbols like __version__ could be included and used
  by the doc tool per default without the user specifying
  any special "Version:: %(__version__)s" % globals() tags.

BTW, for some code which does online formatting of the
doc strings, have a look at my hack.py script. It includes
a function called docs() which prints out all the information
it can find on the given target object.

Here's an example:

>>> docs(string.upper)
upper :
    upper(s) -> string
    
    Return a copy of the string s converted to uppercase.


>>> docs(string.zfill)
zfill(x, width) :
    zfill(x, width) -> string
    
    Pad a numeric string x with zeros on the left, to fill a field
    of the specified width.  The string x is never truncated.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Y2000:                                                    32 days left
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/