[Doc-SIG] non-ascii docstrings

[Edward Loper]

David Goodger wrote:
>> In particular, the question is whether I should assume that the
>> docstring is encoded with the encoding specified by the "-*- coding
>> -*-" directive at the top of the file.
> 
> I think that although it's the only possible assumption, it's also
> potentially a wrong assumption.  IOW, don't assume anything.

That was my inclination at first, but it appears that there are a large 
number of python files out there that use non-ascii docstrings.  Asking 
the epydoc user (who is very often not the package author) to go through 
and add a 'u' in front of every docstring (but *not* any other string -- 
that might break the program) seems unreasonable.  And I have yet to see 
a single python module where the -*- coding -*- directive is *not* the 
right encoding for the docstrings.

> Another reason is simple: "In the face of ambiguity, refuse the
> temptation to guess."

Practicality beats purity. :)

> Yes, it's unreasonable.  But such code is buggy IMO.  It's also
> unreasonable to expect Epydoc to correctly interpret garbage input.

Small consolation to the user who's just trying to learn how to use a 
package that they didn't write.

-Edward