[PATCH 1 of 4] help: adding a new help topic about extensions

[Dirkjan Ochtman]

2009/6/20 Cédric Duval <cedricduval at free.fr>:
> +# borrowed from pydoc
> +def pathdirs():
> +    '''Convert sys.path into a list of absolute, existing, unique paths.'''

Your function comment should be put into the docstring. Doesn't make
much sense to have two separate places to comment on the function.

> +    dirs = []
> +    normdirs = []
> +    for dir in sys.path:
> +        dir = os.path.abspath(dir or '.')
> +        normdir = os.path.normcase(dir)
> +        if normdir not in normdirs and os.path.isdir(dir):
> +            dirs.append(dir)
> +            normdirs.append(normdir)
> +    return dirs
> +
> +# loosely inspired by pydoc.source_synopsis()
> +# rewritten to handle ''' as well as """
> +# and to return the whole text instead of just the synopsis

Same here.

> +def moduledoc(file):
> +    '''Return the top python documentation for the given file'''
> +    result = []
> +
> +    line = file.readline()
> +    while line[:1] == '#' or not line.strip():
> +        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:
> +                return None # unmatched delimiter
> +            result.append(line)
> +            line = file.readline()
> +    else:
> +        return None
> +
> +    return ''.join(result)
> +
> +def additionalextensions():

Don't like the name too much. Maybe disabled()?

> +    '''Find the extensions shipped with Mercurial but not enabled
> +
> +    Returns extensions names and descriptions, and the max name length
> +    '''
> +    exts = {}
> +    maxlength = 0
> +
> +    for dir in filter(os.path.isdir,
> +                      (os.path.join(pd, 'hgext') for pd in pathdirs())):

Please don't use filter. Use a list comprehension instead. For best
results, put it on a separate line so it doesn't wrap.

Might make more sense to leverage os.walk() instead of having a nested
loop here.

> +        for e in os.listdir(dir):
> +            if e.endswith('.py'):
> +                name = e.rsplit('.', 1)[0]
> +                path = os.path.join(dir, e)
> +            else:
> +                name = e
> +                path = os.path.join(dir, e, '__init__.py')
> +
> +            if name in exts or name == '__init__' or not os.path.exists(path):
> +                continue
> +
> +            try:
> +                extensions.find(name)
> +            except KeyError:
> +                pass
> +            else:
> +                continue # enabled extension
> +
> +            try:
> +                file = open(path)
> +            except IOError:
> +                continue
> +            else:
> +                doc = moduledoc(file)
> +                file.close()
> +
> +            if doc: # extracting localized synopsis
> +                exts[name] = gettext(doc).splitlines()[0]
> +            else:
> +                exts[name] = _('(no help text available)')
> +            if len(name) > maxlength:
> +                maxlength = len(name)
> +
> +    return exts, maxlength
> +
> +def topicextensions():

This should probably just be called extensions().

> +    doc = _(r'''
> +    Mercurial has an extension mechanism for adding new features.
> +
> +    To enable an extension "foo" bundled with Mercurial, create an
> +    entry for it your hgrc, like this:
> +
> +       [extensions]
> +       foo =
> +    ''')
> +
> +    exts, maxlength = additionalextensions()
> +    if exts:
> +        doc += _('\nnon-enabled extensions:\n\n')

non-enabled -> disabled.

> +    for name, desc in sorted(exts.iteritems()):
> +        doc += ' %s  %s\n' % (name.ljust(maxlength), desc)
> +
> +    return doc
>
>  helptable = (
>     (["dates"], _("Date Formats"),
> @@ -418,4 +528,5 @@
>       The push command will look for a path named 'default-push', and
>       prefer it over 'default' if both are defined.
>     ''')),
> +    (["extensions"], _("Using additional features"), topicextensions),
>  )

Thanks for working on this!

Cheers,

Dirkjan