doc/runrst

graphmod: allow edges to end early

Rather than draw an edge all the way to the bottom of the graph, make it
possible to end an edge to parents that are not part of the graph early on.
This results in a far cleaner graph.

Any edge type can be set to end early; set the ui.graphstyle.<edgetype>
parameter to the empty string to enable this.

For example, setting the following configuration:

    [ui]
    graphstyle.grandparent = :
    graphstyle.missing =

would result in a graph like this:

  o    changeset:   32:d06dffa21a31
  |\   parent:      27:886ed638191b
  | :  parent:      31:621d83e11f67
  | :
  o :  changeset:   31:621d83e11f67
  |\:  parent:      21:d42a756af44d
  | :  parent:      30:6e11cd4b648f
  | :
  o :    changeset:   30:6e11cd4b648f
  |\ \   parent:      28:44ecd0b9ae99
  | ~ :  parent:      29:cd9bb2be7593
  |  /
  o :    changeset:   28:44ecd0b9ae99
  |\ \   parent:      1:6db2ef61d156
  | ~ :  parent:      26:7f25b6c2f0b9
  |  /
  o :    changeset:   26:7f25b6c2f0b9
  |\ \   parent:      18:1aa84d96232a
  | | :  parent:      25:91da8ed57247
  | | :
  | o :  changeset:   25:91da8ed57247
  | |\:  parent:      21:d42a756af44d
  | | :  parent:      24:a9c19a3d96b7
  | | :
  | o :    changeset:   24:a9c19a3d96b7
  | |\ \   parent:      0:e6eb3150255d
  | | ~ :  parent:      23:a01cddf0766d
  | |  /
  | o :    changeset:   23:a01cddf0766d
  | |\ \   parent:      1:6db2ef61d156
  | | ~ :  parent:      22:e0d9cccacb5d
  | |  /
  | o :  changeset:   22:e0d9cccacb5d
  |/:/   parent:      18:1aa84d96232a
  | :    parent:      21:d42a756af44d
  | :
  | o    changeset:   21:d42a756af44d
  | |\   parent:      19:31ddc2c1573b
  | | |  parent:      20:d30ed6450e32
  | | |
  +---o  changeset:   20:d30ed6450e32
  | | |  parent:      0:e6eb3150255d
  | | ~  parent:      18:1aa84d96232a
  | |
  | o    changeset:   19:31ddc2c1573b
  | |\   parent:      15:1dda3f72782d
  | ~ ~  parent:      17:44765d7c06e0
  |
  o  changeset:   18:1aa84d96232a
     parent:      1:6db2ef61d156
     parent:      15:1dda3f72782d

The default configuration leaves all 3 types set to |.

This is part of the work towards moving smartlog upstream; currently smartlog
injects extra nodes into the graph to indicate grandparent relationships (nodes
elided).

#!/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.stderr.write("please install python-docutils or see "
                     "http://docutils.sourceforge.net/\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:]
    refuri = "hg.1.html#%s" % cmd
    if cmd == 'help' and args:
        if args[0] == 'config':
            # :hg:`help config`
            refuri = "hgrc.5.html"
        elif args[0].startswith('config.'):
            # :hg:`help config.SECTION...`
            refuri = "hgrc.5.html#%s" % args[0].split('.', 2)[1]
        elif len(args) >= 2 and args[0] == '-c':
            # :hg:`help -c COMMAND ...` is equivalent to :hg:`COMMAND`
            # (mainly for :hg:`help -c config`)
            refuri = "hg.1.html#%s" % args[1]
        else:
            refuri = "hg.1.html#%s" % args[0]
    node = nodes.reference(rawtext, '', linktext,
                           refuri=refuri)
    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)