[PATCH 1 of 8] extdoc: separate module for handling extractions of descriptions

[Cédric Duval]

# HG changeset patch
# User Cédric Duval <cedricduval at free.fr>
# Date 1246737838 -7200
# Node ID b48834a6d0e1c68ebe2bee05f5d24a424bfef40b
# Parent  10532b29cdee993efd804c7d60a188347425ebaf
extdoc: separate module for handling extractions of descriptions

Moving moduledoc() from extensions, and adding synopsis().
This module is meant to be used by both hg and external tools.

diff --git a/mercurial/extdoc.py b/mercurial/extdoc.py
new file mode 100644
--- /dev/null
+++ b/mercurial/extdoc.py
@@ -0,0 +1,43 @@
+# exdoc.py - documentation extraction for Mercurial extensions
+#
+# Copyright 2009 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, incorporated herein by reference.
+
+from i18n import gettext
+
+
+def moduledoc(file):
+    '''return the top-level python documentation for the given file
+
+    Loosely inspired by pydoc.source_synopsis(), but rewritten to handle \'''
+    as well as """ and to return the whole text instead of just the synopsis'''
+    result = []
+
+    line = file.readline()
+    while line[:1] == '#' or not line.strip():
+        line = file.readline()
+        if not line: break
+
+    start = line[:3]
+    if start == '"""' or start == "'''":
+        line = line[3:]
+        while line:
+            if line.rstrip().endswith(start):
+                line = line.split(start)[0]
+                if line:
+                    result.append(line)
+                break
+            elif not line:
+                return None # unmatched delimiter
+            result.append(line)
+            line = file.readline()
+    else:
+        return None
+
+    return ''.join(result)
+
+def synopsis(desc):
+    '''return a localized synopsis from the raw description string'''
+    return gettext(desc).splitlines()[0]
diff --git a/mercurial/extensions.py b/mercurial/extensions.py
--- a/mercurial/extensions.py
+++ b/mercurial/extensions.py
@@ -6,7 +6,7 @@
 # GNU General Public License version 2, incorporated herein by reference.
 
 import imp, os
-import util, cmdutil, help
+import util, cmdutil, extdoc
 from i18n import _, gettext
 
 _extensions = {}
@@ -151,11 +151,11 @@
         except IOError:
             continue
         else:
-            doc = help.moduledoc(file)
+            doc = extdoc.moduledoc(file)
             file.close()
 
         if doc: # extracting localized synopsis
-            exts[name] = gettext(doc).splitlines()[0]
+            exts[name] = extdoc.synopsis(doc)
         else:
             exts[name] = _('(no help text available)')
 
@@ -170,9 +170,9 @@
     maxlength = 0
     exthelps = []
     for ename, ext in extensions():
-        doc = (gettext(ext.__doc__) or _('(no help text available)'))
+        doc = ext.__doc__ or '(no help text available)'
         ename = ename.split('.')[-1]
         maxlength = max(len(ename), maxlength)
-        exts[ename] = doc.splitlines(0)[0].strip()
+        exts[ename] = extdoc.synopsis(doc)
 
     return exts, maxlength
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -9,36 +9,6 @@
 import extensions, util
 
 
-def moduledoc(file):
-    '''return the top-level python documentation for the given file
-
-    Loosely inspired by pydoc.source_synopsis(), but rewritten to handle \'''
-    as well as """ and to return the whole text instead of just the synopsis'''
-    result = []
-
-    line = file.readline()
-    while line[:1] == '#' or not line.strip():
-        line = file.readline()
-        if not line: break
-
-    start = line[:3]
-    if start == '"""' or start == "'''":
-        line = line[3:]
-        while line:
-            if line.rstrip().endswith(start):
-                line = line.split(start)[0]
-                if line:
-                    result.append(line)
-                break
-            elif not line:
-                return None # unmatched delimiter
-            result.append(line)
-            line = file.readline()
-    else:
-        return None
-
-    return ''.join(result)
-
 def listexts(header, exts, maxlength):
     '''return a text listing of the given extensions'''
     if not exts: