doc/runrst

contrib/setup3k.py: added script to build hg with py3k

This patch implements a script that inherits most of its functionality from
hg's setup.py and adds support to calling 2to3 during invocation with python3.
The motivation of having this script around is twofold:

 1) It enables py3k crazies to test mercurial in py3k and, hopefully, patch it
    more easily, so it can improve the py3k support to eventually run there.

 2) Being separated from the main setup.py eliminates the need to make hg's
    setup.py even more cluttered, and enables "independent" development until
    the port is done.

Some considerations about the structure of this patch:

Mercurial already overrides the behavior of build_py, this patch tweaks it a bit
more to add support to call 2to3 with a custom fixer* location for Mercurial.
There is also a need of having the core C modules built *before* the
translation process starts, otherwise 2to3 will think those are global modules.

* A fixer is a python module that transforms python 2.x code in python 3.x
code.

#!/usr/bin/env python
#
# runrst - register custom roles and run correct writer
#
# Copyright 2010 Matt Mackall <[e-mail]> and others
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.

"""usage: %s WRITER args...

where WRITER is the name of a Docutils writer such as 'html' or 'manpage'
"""

import sys
try:
    from docutils.parsers.rst import roles
    from docutils.core import publish_cmdline
    from docutils import nodes, utils
except ImportError:
    sys.stderr.write("abort: couldn't generate documentation: docutils "
                     "module is missing\n")
    sys.exit(-1)

def role_hg(name, rawtext, text, lineno, inliner,
            options={}, content=[]):
    text = "hg " + utils.unescape(text)
    linktext = nodes.literal(rawtext, text)
    parts = text.split()
    cmd, args = parts[1], parts[2:]
    if cmd == 'help' and args:
        cmd = args[0] # link to 'dates' for 'hg help dates'
    node = nodes.reference(rawtext, '', linktext,
                           refuri="hg.1.html#%s" % cmd)
    return [node], []

roles.register_local_role("hg", role_hg)

if __name__ == "__main__":
    if len(sys.argv) < 2:
        sys.stderr.write(__doc__ % sys.argv[0])
        sys.exit(1)

    writer = sys.argv[1]
    del sys.argv[1]

    publish_cmdline(writer_name=writer)