[PATCH hgweb-help-followup] help: teach topic symbols how to dedent

[Augie Fackler]

On Mon, Feb 09, 2015 at 03:06:03PM -0800, Gregory Szorc wrote:
> # HG changeset patch
> # User Gregory Szorc <gregory.szorc at gmail.com>
> # Date 1423522744 28800
> #      Mon Feb 09 14:59:04 2015 -0800
> # Node ID bd6a8cf1710d95b593babf3cad3224adff6064f9
> # Parent  1f4fd12991f2b32b1277bd3e047132d5f087b914
> help: teach topic symbols how to dedent
>
> When using docstrings for documenting symbols such as revsets,
> templates, or hgweb commands, documentation likely has leading
> whitespace corresponding to the indentation from the Python source
> file.
>
> Up until this point, the help system stripped all leading and
> trailing whitespace and replaced it with 2 spaces of leading
> whitespace. There were a few bad side-effects. First, sections
> could not be used in docstrings because they would be indented
> and the rst parser would fail to parse them as sections. Also,
> any rst elements that required indentation would lose their
> indentation, again causing them to be parsed and rendered
> incorrectly.
>
> In this patch, we teach the topic symbols system how to dedent
> text properly. I argue this mode should be enabled by default.
> However, I stopped short of changing that because it would cause
> a lot of documentation reformatting to occur. I'm not sure if
> people are relying on or wanting indentation. So, dedenting has
> only been turned on for hgweb symbols. This decision should be
> scrutinized.

This looks reasonable, as does the conservative approach. A good
followup series (IMO) would be to figure out what can't handle
dedentation and fix that up so we can just turn this on globally.

Queued, and hopefully will push the hgweb-help series soon.

>
> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -5,9 +5,9 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2 or any later version.
>
>  from i18n import gettext, _
> -import itertools, os
> +import itertools, os, textwrap
>  import error
>  import extensions, revset, fileset, templatekw, templatefilters, filemerge
>  import encoding, util, minirst
>  import cmdutil
> @@ -171,9 +171,9 @@ helphooks = {}
>
>  def addtopichook(topic, rewriter):
>      helphooks.setdefault(topic, []).append(rewriter)
>
> -def makeitemsdoc(topic, doc, marker, items):
> +def makeitemsdoc(topic, doc, marker, items, dedent=False):
>      """Extract docstring from the items key to function mapping, build a
>      .single documentation block and use it to overwrite the marker in doc
>      """
>      entries = []
> @@ -181,30 +181,36 @@ def makeitemsdoc(topic, doc, marker, ite
>          text = (items[name].__doc__ or '').rstrip()
>          if not text:
>              continue
>          text = gettext(text)
> +        if dedent:
> +            text = textwrap.dedent(text)
>          lines = text.splitlines()
>          doclines = [(lines[0])]
>          for l in lines[1:]:
>              # Stop once we find some Python doctest
>              if l.strip().startswith('>>>'):
>                  break
> -            doclines.append('  ' + l.strip())
> +            if dedent:
> +                doclines.append(l.rstrip())
> +            else:
> +                doclines.append('  ' + l.strip())
>          entries.append('\n'.join(doclines))
>      entries = '\n\n'.join(entries)
>      return doc.replace(marker, entries)
>
> -def addtopicsymbols(topic, marker, symbols):
> +def addtopicsymbols(topic, marker, symbols, dedent=False):
>      def add(topic, doc):
> -        return makeitemsdoc(topic, doc, marker, symbols)
> +        return makeitemsdoc(topic, doc, marker, symbols, dedent=dedent)
>      addtopichook(topic, add)
>
>  addtopicsymbols('filesets', '.. predicatesmarker', fileset.symbols)
>  addtopicsymbols('merge-tools', '.. internaltoolsmarker', filemerge.internals)
>  addtopicsymbols('revsets', '.. predicatesmarker', revset.symbols)
>  addtopicsymbols('templates', '.. keywordsmarker', templatekw.dockeywords)
>  addtopicsymbols('templates', '.. filtersmarker', templatefilters.filters)
> -addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands)
> +addtopicsymbols('hgweb', '.. webcommandsmarker', webcommands.commands,
> +                dedent=True)
>
>  def help_(ui, name, unknowncmd=False, full=True, **opts):
>      '''
>      Generate the help for 'name' as unformatted restructured text. If
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel