[PATCH 6 of 6] highlight: use docutils for generating help if possible

[Martin Geisler]

Dan Villiom Podlaski Christiansen <danchr at gmail.com> writes:

> # HG changeset patch
> # User Dan Villiom Podlaski Christiansen  <danchr at gmail.com>
> # Date 1360414108 0
> # Node ID 40da011562a84f69cd3c198e9c44cd4545bdeedb
> # Parent  45b34ea40358b6f8fe14ef874ebbc5de5556f23c
> highlight: use docutils for generating help if possible

I really like the idea of trying to use Docutils for HTML generation if
it's available -- redoing their work feels suboptimal to me.

I'm not a fan of putting this into the highlight extension, which in my
mind is an extension for enabling pygments in hgweb. A smaller and more
targeted extension feels better to me -- hgwebrst maybe?

> diff --git a/hgext/highlight/__init__.py b/hgext/highlight/__init__.py
> --- a/hgext/highlight/__init__.py
> +++ b/hgext/highlight/__init__.py
> @@ -21,9 +21,13 @@ There is a single configuration option::
>  The default is 'colorful'.
>  """
>  
> -import highlight
> +import highlight, rst
> +
>  from mercurial.hgweb import webcommands, webutil, common
> -from mercurial import extensions, encoding
> +from mercurial import extensions, encoding, minirst
> +
> +import cgi, traceback
> +
>  testedwith = 'internal'
>  
>  def filerevision_highlight(orig, web, tmpl, fctx):
> @@ -48,6 +52,24 @@ def annotate_highlight(orig, web, req, t
>          highlight.pygmentize('annotateline', fctx, style, tmpl)
>      return orig(web, req, tmpl)
>  
> +def format_docutils(orig, *args, **opts):
> +    if opts.get('style') == 'html':
> +        try:
> +            return rst.publish(args[0])
> +        except Exception:

That's too general: you ought to detect if docutils is there by catching
an ImportError (above).

That is something like

try:
    from docutils import core
except ImportError:
    core = None

and then later

  if core is None:
      # fallback
  else:
      # use core.publish_parts

> --- /dev/null
> +++ b/hgext/highlight/rst.py
> @@ -0,0 +1,32 @@
> +# rst.py - generate HTML from docutils source
> +#
> +# Copyright 2010-2013 Matt Mackall <mpm at selenic.com> 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.
> +#
> +# The original module was split in an interface and an implementation
> +# file to defer pygments loading and speedup extension setup.

I think you've copied that header from another highlight file and copied
too much here.

> +from docutils.parsers.rst import roles
> +from docutils import core, nodes, utils
> +
> +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="%s" % cmd)
> +    return [node], []
> +
> +roles.register_local_role("hg", role_hg)
> +
> +def publish(text, **opts):
> +    parts = core.publish_parts(text, writer_name='html',
> +                               enable_exit_status=True, **opts)

Doesn't enable_exit_status=True mean that docutils will exit the program
if it encounters an error? (... moments later...) Yeah, I found this in
docutils.core:

        if (enable_exit_status and self.document
            and (self.document.reporter.max_level
                 >= self.settings.exit_status_level)):
            sys.exit(self.document.reporter.max_level + 10)

-- 
Martin Geisler