doc/runrst

emitrevision: consider ancestors revision to emit as available base

This should make more delta base valid. This notably affects:

* case where we skipped some parent with empty delta to directly delta against
  an ancestors
* case where an intermediate snapshots is stored.

This change means we could sent largish intermediate snapshots over the wire.
However this is actually a sub goal here. Sending snapshots over the wire means
the client have a high odd of simply storing the pre-computed delta instead of
doing a lengthy process that will… end up doing the same intermediate snapshot.

In addition the overall size of snapshot (or any level) is "only" some or the
overall delta size. (0.17% for my mercurial clone, 20% for my clone of Mozilla
try). So Sending them other the wire is unlikely to change large impact on the
bandwidth used.

If we decide that minimising the bandwidth is an explicit goal, we should
introduce new logic to filter-out snapshot as delta. The current code has no
notion explicite of snapshot so far, they just tended to fall into the wobbly
filtering options.

In some cases, this patch can yield large improvement to the bundling time:

    ### data-env-vars.name      = mozilla-try-2019-02-18-zstd-sparse-revlog
      # benchmark.name          = perf-bundle
      # benchmark.variants.revs = last-100000
    before: 68.787066 seconds
    after:  47.552677 seconds (-30.87%)

That translate to large improvement to the pull time :

    ### data-env-vars.name           = mozilla-try-2019-02-18-zstd-sparse-revlog
      # benchmark.name               = pull
      # benchmark.variants.issue6528 = disabled
      # benchmark.variants.revs      = last-100000
    before: 142.186625 seconds
    after:   75.897745 seconds  (-46.62%)

No significant negative impact have been observed.

#!/usr/bin/env python3
#
# runrst - register custom roles and run correct writer
#
# Copyright 2010 Olivia 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:
    import docutils.core as core
    import docutils.nodes as nodes
    import docutils.utils as utils
    import docutils.parsers.rst.roles as roles
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=None, content=None):
    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]

    core.publish_cmdline(writer_name=writer)