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

[Martin Geisler]

Cedric Duval <cedricduval at free.fr> writes:

> Martin Geisler wrote:
>> Cédric Duval <cedricduval at free.fr> writes:
>> > -        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.
>
> Actually the right thing to do here is use N_().

You're right, I had forgotten about that convention.

> [...] Not so much new code in fact, merely this quite verbose
> refactoring. But once things have been moved into extdoc, everything
> falls into place naturally, and the same code is re-used by hg, gendoc
> and setup.

And i18n/hggettext. That script is actually already using the
"alternative" approach of importing modules to extract docstrings.

Maybe we could move the code into its own module and import that from
everywhere.

>> [...] it actually works... :-) It's very cool to have a description
>> of all the extensions in the hg.1 man page.
>
> Glad you like it. :) Though the resulting (non-)wrapping in the man
> page is less than optimal, when read in a 80 characters wide
> terminal...

True, but we know what the problem is there: we create literal block in
our asciidoc sources, just take a look at the HTML version to see. So we
can fix that in another round of patches, hopefully be switching to a
format with a more sensible syntax.

>> As I see it, the only problem with importing modules is to figure out
>> the list of importable modules. That we can do a build-time and amend
>> it at run-time with os.listdir if we're dealing with normal .py
>> files.
>
> That might be a compromise. Then with third-party extensions found at
> runtime, parsing or importing?

I suggest importing always: we extract docstrings just like we do today.
If people install new extensions into hgext we should import those as
well if we can discover them, i.e., provided hgext is a normal directory
we can use os.listdir on.

We should of course try to import the modules carefully and fail
gracefully -- this is not different from the situation where a system
administrator installs some buggy third-party extension and a user
enables it.

The built-in list of extension would only be used in situations where we
cannot discover extensions at run-time. The list would be a list like

  ['acl', 'mq', 'convert']

and we would try to import 'hgext.acl', ..., from the library.zip file.

-- 
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/e15a7646/attachment.pgp