epydoc, variables and encoding

[Kenneth Pronovici]

>   I found a "problem" on epydoc. If I specify an encoding, epydoc not find 
>   my global variables, and if I remove it, it work well.
>
>   code.py:
>
>      #!/usr/bin/env python
>      # -*- coding: utf-8 -*-
>
>      MY_VAR = None
>
>      class foo(object):
>         def __init__(self, foo):
>         """
>         Some text
>         @param foo: Pass me what you want
>         @type foo: A type
>         @return: The object
>         """
>         return foo
>
>   This not work (MY_VAR is silently skipped), but if I remove:
>   # -*- coding: utf-8 -*-
>
>   it see MY_VAR and put it to my html file.
>
>   Is it normal?

No, it's not normal, and I'm fairly sure it's a bug.  The problem is
that the extra encoding statement at the top of the file changes the AST
parse tree that epydoc uses, which confuses epydoc.

There seem to be two solutions.  The first is easy.  Just add a @var
entry to the module docstring, listing MY_VAR.  Epydoc seems to notice
the variable if you do that.

   #!/usr/bin/env python
   # -*- coding: utf-8 -*-
   """
   @var MY_VAR: Is a variable
   """

Otherwise, you can try applying the following patch:

Index: objdoc.py
===================================================================
RCS file: /cvsroot/epydoc/epydoc/src/epydoc/objdoc.py,v
retrieving revision 1.93
diff -u -r1.93 objdoc.py
--- objdoc.py   12 Jan 2005 16:11:02 -0000      1.93
+++ objdoc.py   5 Oct 2005 19:56:00 -0000
@@ -1345,9 +1345,15 @@

         # Construct a list of defined variables.  To do this, we search
         # the parse tree for statements of the form "a=b" or "a=b=c" or
-        # "a,b=c" or "(a,b)=c" or "[a,b]=c".
+        # "a,b=c" or "(a,b)=c" or "[a,b]=c".  We have to make sure to
+        # strip any encoding statement off the front first, though.
         defined_variables = {}
-        for stmt in ast.totuple()[1:]:
+        stmts = ast.totuple()
+        if symbol.sym_name[stmts[0]] == "encoding_decl":
+            stmts = stmts[1:][0][1:]
+        else:
+            stmts = stmts[1:]
+        for stmt in stmts:
             dict = {}
             if _ast_match(self._EXPR_STMT_PATTERN, stmt, dict)[0]:
                 expr_stmt = dict['expr_stmt']

Maybe Edward won't like this patch, but since he seems to be unreachable
for the last six months <sigh>, you'll have to settle for my
less-than-educated guess at a fix. :)

KEN

-- 
Kenneth J. Pronovici <pronovic at ieee.org>
http://www.cedar-solutions.com/