Patchwork [3,of,6] help: ReST tweaks

login
register
mail settings
Submitter Dan Villiom Podlaski Christiansen
Date Feb. 9, 2013, 1 p.m.
Message ID <03c9cfc461cce54da65f.1360414837@s0-0.paconsult7.bbnplanet.net>
Download mbox | patch
Permalink /patch/861/
State Superseded, archived
Delegated to: Augie Fackler
Headers show

Comments

Dan Villiom Podlaski Christiansen - Feb. 9, 2013, 1 p.m.
# HG changeset patch
# User Dan Villiom Podlaski Christiansen  <danchr@gmail.com>
# Date 1360414103 0
# Node ID 03c9cfc461cce54da65f0ad0529a734181022b83
# Parent  aa74feb1f11d43453e6ef3797e6c4c24f950a9dc
help: ReST tweaks

Use a full header for topic titles; make the indent configurable by
the caller
Pierre-Yves David - Feb. 9, 2013, 1:57 p.m.
On Sat, Feb 09, 2013 at 01:00:37PM +0000, Dan Villiom Podlaski Christiansen wrote:
> # HG changeset patch
> # User Dan Villiom Podlaski Christiansen  <danchr@gmail.com>
> # Date 1360414103 0
> # Node ID 03c9cfc461cce54da65f0ad0529a734181022b83
> # Parent  aa74feb1f11d43453e6ef3797e6c4c24f950a9dc
> help: ReST tweaks
> 
> Use a full header for topic titles; make the indent configurable by
> the caller

This patches is doing two stuff, you should probably split it.

The changes to header is a bit obscure to me. looks like you are adding a '==='
belong the header. But it must have been something there before. Why is that necessary ?

> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -389,12 +389,17 @@ def help_(ui, name, unknowncmd=False, fu
>          else:
>              raise error.UnknownCommand(name)
>  
> -        rst = ["%s\n\n" % header]
> +        headerstyleline = '=' * encoding.colwidth(header)
> +        rst = ["%s\n%s\n%s\n\n" % (headerstyleline, header, headerstyleline)]
> +
>          # description
>          if not doc:
> -            rst.append("    %s\n" % _("(no help text available)"))
> +            doc = _("(no help text available)")
>          if util.safehasattr(doc, '__call__'):
> -            rst += ["    %s\n" % l for l in doc().splitlines()]
> +            doc = doc()
> +
> +        indent = ' ' * int(opts.get('indent', 4))
> +        rst += ["%s%s\n" % (indent, l) for l in doc.splitlines()]

The new `indent` argument should be documented. (note: having the default value
in the middle of the function is common but confusing)
Martin Geisler - Feb. 9, 2013, 11:07 p.m.
Dan Villiom Podlaski Christiansen <danchr@gmail.com> writes:

> # HG changeset patch
> # User Dan Villiom Podlaski Christiansen  <danchr@gmail.com>
> # Date 1360414103 0
> # Node ID 03c9cfc461cce54da65f0ad0529a734181022b83
> # Parent  aa74feb1f11d43453e6ef3797e6c4c24f950a9dc
> help: ReST tweaks
>
> Use a full header for topic titles; make the indent configurable by
> the caller
>
> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -389,12 +389,17 @@ def help_(ui, name, unknowncmd=False, fu
>          else:
>              raise error.UnknownCommand(name)
>  
> -        rst = ["%s\n\n" % header]
> +        headerstyleline = '=' * encoding.colwidth(header)
> +        rst = ["%s\n%s\n%s\n\n" % (headerstyleline, header, headerstyleline)]

When we discussed this I had a strong feeling that we already had this
code available somewhere: it's in doc/gendoc.py :) Maybe you could move
this into minirst and then let gendoc import it back -- that way we get
consistent headings.
Martin Geisler - Feb. 9, 2013, 11:10 p.m.
Dan Villiom Podlaski Christiansen <danchr@gmail.com> writes:

> # HG changeset patch
> # User Dan Villiom Podlaski Christiansen  <danchr@gmail.com>
> # Date 1360414103 0
> # Node ID 03c9cfc461cce54da65f0ad0529a734181022b83
> # Parent  aa74feb1f11d43453e6ef3797e6c4c24f950a9dc
> help: ReST tweaks
>
> Use a full header for topic titles; make the indent configurable by
> the caller
>
> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -389,12 +389,17 @@ def help_(ui, name, unknowncmd=False, fu
>          else:
>              raise error.UnknownCommand(name)
>  
> -        rst = ["%s\n\n" % header]
> +        headerstyleline = '=' * encoding.colwidth(header)
> +        rst = ["%s\n%s\n%s\n\n" % (headerstyleline, header, headerstyleline)]
> +
>          # description
>          if not doc:
> -            rst.append("    %s\n" % _("(no help text available)"))
> +            doc = _("(no help text available)")
>          if util.safehasattr(doc, '__call__'):
> -            rst += ["    %s\n" % l for l in doc().splitlines()]
> +            doc = doc()
> +
> +        indent = ' ' * int(opts.get('indent', 4))
> +        rst += ["%s%s\n" % (indent, l) for l in doc.splitlines()]

The minirst.format function has an indent argument -- can that not be
used instead?

Patch

diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -389,12 +389,17 @@  def help_(ui, name, unknowncmd=False, fu
         else:
             raise error.UnknownCommand(name)
 
-        rst = ["%s\n\n" % header]
+        headerstyleline = '=' * encoding.colwidth(header)
+        rst = ["%s\n%s\n%s\n\n" % (headerstyleline, header, headerstyleline)]
+
         # description
         if not doc:
-            rst.append("    %s\n" % _("(no help text available)"))
+            doc = _("(no help text available)")
         if util.safehasattr(doc, '__call__'):
-            rst += ["    %s\n" % l for l in doc().splitlines()]
+            doc = doc()
+
+        indent = ' ' * int(opts.get('indent', 4))
+        rst += ["%s%s\n" % (indent, l) for l in doc.splitlines()]
 
         if not ui.verbose:
             omitted = (_('use "hg help -v %s" to show more complete help') %