[PATCH 1 of 8] extdoc: separate module for handling extractions of descriptions

[Martin Geisler]

Cédric Duval <cedricduval at free.fr> writes:

> # HG changeset patch
> # User Cédric Duval <cedricduval at free.fr>
> # Date 1246737838 -7200
> # Node ID b48834a6d0e1c68ebe2bee05f5d24a424bfef40b
> # Parent  10532b29cdee993efd804c7d60a188347425ebaf
> extdoc: separate module for handling extractions of descriptions
>
> Moving moduledoc() from extensions, and adding synopsis().
> This module is meant to be used by both hg and external tools.

Perhaps we should write that in a comment at the top: This module should
be importable without building the C extensions.

> diff --git a/mercurial/extdoc.py b/mercurial/extdoc.py
> new file mode 100644
> --- /dev/null
> +++ b/mercurial/extdoc.py
> @@ -0,0 +1,43 @@
> +# exdoc.py - documentation extraction for Mercurial extensions
> +#
> +# Copyright 2009 Matt Mackall <mpm at selenic.com> and others
> +#
> +# This software may be used and distributed according to the terms of the
> +# GNU General Public License version 2, incorporated herein by reference.
> +
> +from i18n import gettext
> +
> +
> +def moduledoc(file):
> +    '''return the top-level python documentation for the given file
> +
> +    Loosely inspired by pydoc.source_synopsis(), but rewritten to handle \'''
> +    as well as """ and to return the whole text instead of just the synopsis'''
> +    result = []
> +
> +    line = file.readline()
> +    while line[:1] == '#' or not line.strip():

line[:1] should just be line[0]

> +        line = file.readline()
> +        if not line: break
> +
> +    start = line[:3]
> +    if start == '"""' or start == "'''":
> +        line = line[3:]
> +        while line:
> +            if line.rstrip().endswith(start):
> +                line = line.split(start)[0]
> +                if line:
> +                    result.append(line)
> +                break
> +            elif not line:

I don't think this branch can ever be true. If we enter the while loop,
then 'not line' is False.

> +                return None # unmatched delimiter
> +            result.append(line)
> +            line = file.readline()
> +    else:
> +        return None
> +
> +    return ''.join(result)
> +
> +def synopsis(desc):
> +    '''return a localized synopsis from the raw description string'''
> +    return gettext(desc).splitlines()[0]
> diff --git a/mercurial/extensions.py b/mercurial/extensions.py
> --- a/mercurial/extensions.py
> +++ b/mercurial/extensions.py
> @@ -6,7 +6,7 @@
>  # GNU General Public License version 2, incorporated herein by reference.
>  
>  import imp, os
> -import util, cmdutil, help
> +import util, cmdutil, extdoc
>  from i18n import _, gettext
>  
>  _extensions = {}
> @@ -151,11 +151,11 @@
>          except IOError:
>              continue
>          else:
> -            doc = help.moduledoc(file)
> +            doc = extdoc.moduledoc(file)
>              file.close()
>  
>          if doc: # extracting localized synopsis
> -            exts[name] = gettext(doc).splitlines()[0]
> +            exts[name] = extdoc.synopsis(doc)
>          else:
>              exts[name] = _('(no help text available)')
>  
> @@ -170,9 +170,9 @@
>      maxlength = 0
>      exthelps = []
>      for ename, ext in extensions():
> -        doc = (gettext(ext.__doc__) or _('(no help text available)'))
> +        doc = ext.__doc__ or '(no help text available)'

It's unfortunate to have a raw string without the _(...) function. It
will only be translated because the same string occurs in commands.py.
So I think there should at least be a comment.

> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -9,36 +9,6 @@
>  import extensions, util

[...]

> -        while line:
> -            if line.rstrip().endswith(start):
> -                line = line.split(start)[0]
> -                if line:
> -                    result.append(line)
> -                break
> -            elif not line:
> -                return None # unmatched delimiter

Oh, I just realized that you just moved this code... But I still think
this branch should be removed.

-- 
Martin Geisler

VIFF (Virtual Ideal Functionality Framework) brings easy and efficient
SMPC (Secure Multiparty Computation) to Python. See: http://viff.dk/.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
Url : http://selenic.com/pipermail/mercurial-devel/attachments/20090707/1732e878/attachment.pgp