doc strings not appearing in help command

[GoogleCodeExporter]

What steps will reproduce the problem?
1. use the "help" command

What is the expected output? What do you see instead?
I expect all docstrings to appear in the output, but many functions do not
appear to have a docstring.  In particular, the following functions have no
docstring in the help, despite having docstrings in the code.

apply
cat
head
ls
open
pprint
py-eval
sechash
setenv
tail

What version of the product are you using? On what operating system?
latest from svn (1254) on ubuntu 8.04

Please provide any additional information below.

What these all have in common is that they are simple functions
incorporated using the @builtin_hotwire decorator.  And they all have a
docstring declared using gettext - _("""docstring""")

However I'm not sure that the docstring gets assigned to __doc__ when it is
in _() - I've just started learning python so it's possible there's some
magic future step that would fix this, such as some po file magic, but if
not, I have a possible solution:

Basically do the gettext inside the decorator function, and have a plain
docstring in the function.

Specifically, in hotwire/builtin.py in the class PyFuncBuiltin in the
__init__ function, change line 220

kwargs['doc'] = inspect.getdoc(func)

to 

kwargs['doc'] = _(inspect.getdoc(func))

Does this sound reasonable?  I've attached a patch that would do this, and
works for me (ie fixes the help command).  The downside might be that
automatic gettext tools would not find the docstrings in the functions if
the gettext call is to inspect.getdoc() ...

Original issue reported on code.google.com by dmi...@gmail.com on 28 May 2008 at 5:03

Attachments:

• doc.patch

[GoogleCodeExporter]

Hm, the problem with this is that I think translation infrastructure won't 
handle the
change.  I wonder if we explicitly assign to __doc__ if that would work?

Original comment by cgwalt...@gmail.com on 5 Jun 2008 at 3:15

• Changed state: Accepted

[GoogleCodeExporter]

I did try explicitly assigning to __doc__, but that doesn't seem to work when 
there
is only the function there - as there is for the builtins I mention above.

So one option would be to explicitly make them all classes.  The 
@builtin_hotwire()
would become the __init__() and the __doc__ class variable would be set 
explicitly.

Another alternative would be to put the docstring explicitly in the
@builtin_hotwire() call.  So for example in hotwire/builtins/apply.py we would 
have

@builtin_hotwire(options_passthrough=True,
                 input=InputStreamSchema('any'),
                 doc=_("""Like Unix xargs - take input and convert to arguments."""))
def apply(context, *args):
    ...

Finally I note that pygettext has an option for extracting docstrings.  From 
the man
page:

       -D, --docstrings
              Extract module, class, method, and function docstrings.  These do not
need  to  be
              wrapped  in  _()  markers,  and in fact cannot be for Python to
consider them doc‐
              strings. (See also the -X option).

[snip unrelated options]

       -X, --no-docstrings=FILENAME
              Specify a file that contains a list of files (one per line) that should
 not  have
              their docstrings extracted.  This is only useful in conjunction with
the -D option
              above.

Ideally we would want to have something like the -X option that would name only 
the
files we do want to extract the strings from.  Maybe adding that to pygettext 
would
be the way to go ...

Original comment by dmi...@gmail.com on 5 Jun 2008 at 8:06

[GoogleCodeExporter]

Actually reading a bit more about pygettext, it looks like we could just pass 
it the
particular files we want with the -D option.  That being the files for the 
builtins I
mention at the top.

Not sure how that would integrate with the general method of generating po files
though ...

Original comment by dmi...@gmail.com on 5 Jun 2008 at 8:13

[GoogleCodeExporter]

Had a quick play with pygettext.  I used 

fsearch "@builtin_hotwire" | uniq path | apply pygettext -D

and I've attached the messages.pot file it produced.  Note that I did this with 
doc
strings that were not inside _()

So would it be possible to integrate this with the translation infrastructure?  
If it
needs to use bash, we could do

grep -l "@builtin_hotwire" | xargs pygettext -D

Original comment by dmi...@gmail.com on 4 Jul 2008 at 4:29

[GoogleCodeExporter]

Just noticed I didn't attach the file - here it is

Original comment by dmi...@gmail.com on 12 Jul 2008 at 5:22

Attachments:

• messages.pot

[GoogleCodeExporter]

I think messages.pot is an older kind of .po file?  Not totally sure about 
this. 
Looking at some current GNOME projects there is no messages.pot but instead a 
layout
like:

po/en_CA.po
po/LINGUAS
po/POTFILES.in
po/POTFILES.skip

I just successfully internationalized hotssh (http://svn.gnome.org/svn/hotssh) 
using
this method and the waf build system.  But this may not be totally right.  If 
we're
going to keep using distutils we should find a real project using the distutils 
po
stuff..

Original comment by cgwalt...@gmail.com on 12 Jul 2008 at 7:00

[GoogleCodeExporter]

OK tried another approach.  I've moved the doc string into the builtin_hotwire 
call.
 So, for example, cat.py goes from 

@builtin_hotwire(output=str,
                 idempotent=True)
def cat(context, *files):
    _("""Yield content lines from file path arguments.""")    

to

@builtin_hotwire(output=str,
                 idempotent=True,
                doc=_("""Yield content lines from file path arguments."""))
def cat(context, *files):

It also required a line to be removed from PyFuncBuiltin (hotwire/builtin.py) - 
see
the attached patch for details.

This patch does mean that the doc strings do appear in the help output.

Original comment by dmi...@gmail.com on 22 Jul 2008 at 9:54

Attachments:

• doc2.patch