help: teach topic symbols how to dedent
authorGregory Szorc <gregory.szorc@gmail.com>
Mon, 09 Feb 2015 14:59:04 -0800
changeset 24098 067540702f64
parent 24097 8e04a73b5502
child 24099 be83fd9d46d5
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.
mercurial/help.py
--- a/mercurial/help.py	Fri Feb 06 22:25:40 2015 -0800
+++ b/mercurial/help.py	Mon Feb 09 14:59:04 2015 -0800
@@ -6,7 +6,7 @@
 # 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
@@ -172,7 +172,7 @@
 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
     """
@@ -182,20 +182,25 @@
         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)
@@ -203,7 +208,8 @@
 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):
     '''