annotate doc/README @ 28450:155e3308289c

hgext: officially turn 'hgext' into a namespace package

Actually since Python 2.3, there is some way to turn top level package into
"namespace package" so that multiple subpackage installed in different part of
the path can still be imported transparently. This feature was previously
thought (at least by myself) to be only provided by some setuptool black magic.

Turning hgext into such namespace package allows third extensions to install
themselves inside the "hgext" namespace package to avoid polluting the global
python module namespace. They will now be able to do so without making it a pain
to use a Mercurial "installed" in a different way/location than these
extensions.

The only constrains is that the extension ship a 'hgext/__init__.py' containing
the same call to 'pkgutil.extend_path' and nothing else. This seems realistic.

The main question that remains is: should we introduce a dedicated namespace for
third party extension (hgext3rd?) to make a clearer distinction between what is
officially supported and what is not? If so, this will be introduced in a follow
up patch.

Mercurial's documentation is kept in reStructuredText format, which is
a simple plain text format that's easy to read and edit:

  http://docutils.sourceforge.net/rst.html

It's also convertible to a variety of other formats including standard
UNIX man page format and HTML. You'll need to install Docutils:

  http://docutils.sourceforge.net/

Use the Makefile in this directory to generate the man and HTML pages.