[Numpy-discussion] ANN: NumPy/SciPy Documentation Marathon 2008

[Pauli Virtanen]

ti, 2008-05-20 kello 18:04 -0500, Robert Kern kirjoitti:
> On Tue, May 20, 2008 at 5:55 PM, Jonathan Wright <wright at esrf.fr> wrote:
> > Stéfan van der Walt wrote:
> >  > As for internationali(s/z)ation, we'll see who writes the most
> >  > docstrings.
> >
> > Indeed. There are some notes on the OLPC wiki at
> >
> > http://wiki.laptop.org/go/Python_i18n
> >
> > It seems to be just a question of adding at the top of add_newdocs.py
> >
> > from gettext import gettext as _
> >
> > ... and putting the docstrings in a _() function call, although perhaps
> > I miss something important, like a performance hit?
>
> Possibly a significant one. This could affect startup times, which I
> am hesitant to make worse.
> 
> > This would catch
> > everything in add_newdocs at least. It seems like a relatively minor
> > change if you are overhauling anyway?
> 
> add_newdocs() could do that, but the usual function docstrings can't.
> The rule is that if the first statement in a function is a literal
> string, then the compiler will assign it func.__doc__. Expressions are
> just treated as expressions in the function body and have no affect on
> func.__doc__.

I think it would be quite straightforward to write a function that
crawled over the numpy namespace and dynamically replaced __doc__ with
gettextized versions. The user could call this function to switch the
language and the reference manual authors could call it to produce
localized versions of the manual. Moreover, we already have tools to
extract English docstrings from numpy and producing .pot files for
gettext could be done. I think i18n of numpy (or any other Python
module) is technically not as far out as it initially seems!

(This is assuming that there are no objects there that don't allow
changing their __doc__.)

But I believe that in practice, we really had better to concentrate on
improving the documentation in English before thinking about spending
much effort on i18n or l10n.

-- 
Pauli Virtanen