launchpad-reviewers team mailing list archive

[Gavin Panella <gavin.panella@xxxxxxxxxxxxx>]

Gavin Panella has proposed merging lp:~allenap/maas/maas-cli-prettier-docs into lp:maas.

Commit message:
Prevent argparse from reformatting help text, and do less processing on help text in the API description.

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)
Related bugs:
  Bug #1059984 in MAAS: "maas-cli help is hard to read"
  https://bugs.launchpad.net/maas/+bug/1059984

For more details, see:
https://code.launchpad.net/~allenap/maas/maas-cli-prettier-docs/+merge/128396
-- 
https://code.launchpad.net/~allenap/maas/maas-cli-prettier-docs/+merge/128396
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~allenap/maas/maas-cli-prettier-docs into lp:maas.

=== modified file 'src/maascli/__init__.py'
--- src/maascli/__init__.py	2012-10-05 05:12:01 +0000
+++ src/maascli/__init__.py	2012-10-07 22:09:22 +0000
@@ -15,6 +15,7 @@
     ]
 
 import argparse
+from argparse import RawDescriptionHelpFormatter
 import locale
 import sys
 
@@ -33,6 +34,10 @@
     a lazily evaluated `subparsers` property.
     """
 
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("formatter_class", RawDescriptionHelpFormatter)
+        super(ArgumentParser, self).__init__(*args, **kwargs)
+
     def add_subparsers(self):
         raise NotImplementedError(
             "add_subparsers has been disabled")
@@ -43,7 +48,8 @@
             return self.__subparsers
         except AttributeError:
             parent = super(ArgumentParser, self)
-            self.__subparsers = parent.add_subparsers(title="commands")
+            self.__subparsers = parent.add_subparsers(title="drill down")
+            self.__subparsers.metavar = "COMMAND"
             return self.__subparsers
 
 

=== modified file 'src/maascli/tests/test_utils.py'
--- src/maascli/tests/test_utils.py	2012-09-27 01:39:52 +0000
+++ src/maascli/tests/test_utils.py	2012-10-07 22:09:22 +0000
@@ -46,39 +46,18 @@
             utils.parse_docstring("Title"))
 
     def test_unwrapping(self):
-        # parse_docstring dedents and unwraps the title and body paragraphs.
-        self.assertEqual(
-            ("Title over two lines",
-             "Paragraph over two lines\n\n"
-             "Another paragraph over two lines"),
-            utils.parse_docstring("""
-                Title over
-                two lines
-
-                Paragraph over
-                two lines
-
-                Another paragraph
-                over two lines
-                """))
-
-    def test_no_unwrapping_for_indented_paragraphs(self):
-        # parse_docstring dedents body paragraphs, but does not unwrap those
-        # with indentation beyond the rest.
-        self.assertEqual(
-            ("Title over two lines",
-             "Paragraph over two lines\n\n"
-             "  An indented paragraph\n  which will remain wrapped\n\n"
-             "Another paragraph over two lines"),
-            utils.parse_docstring("""
-                Title over
-                two lines
-
-                Paragraph over
-                two lines
-
-                  An indented paragraph
-                  which will remain wrapped
+        # parse_docstring unwraps the title paragraph, and dedents the body
+        # paragraphs.
+        self.assertEqual(
+            ("Title over two lines",
+             "Paragraph over\ntwo lines\n\n"
+             "Another paragraph\nover two lines"),
+            utils.parse_docstring("""
+                Title over
+                two lines
+
+                Paragraph over
+                two lines
 
                 Another paragraph
                 over two lines

=== modified file 'src/maascli/utils.py'
--- src/maascli/utils.py	2012-09-27 01:39:52 +0000
+++ src/maascli/utils.py	2012-10-07 22:09:22 +0000
@@ -19,9 +19,11 @@
     ]
 
 from functools import partial
-from inspect import getdoc
+from inspect import (
+    cleandoc,
+    getdoc,
+    )
 import re
-from textwrap import dedent
 from urllib import quote_plus
 
 
@@ -38,26 +40,19 @@
 
 
 def parse_docstring(thing):
-    doc = thing if isinstance(thing, (str, unicode)) else getdoc(thing)
-    doc = empty if doc is None else doc.expandtabs().strip()
+    is_string = isinstance(thing, basestring)
+    doc = cleandoc(thing) if is_string else getdoc(thing)
+    doc = empty if doc is None else doc
     # Break the docstring into two parts: title and body.
     parts = docstring_split(doc)
     if len(parts) == 2:
-        title, body = parts[0], dedent(parts[1])
+        title, body = parts[0], parts[1]
     else:
         title, body = parts[0], empty
     # Remove line breaks from the title line.
     title = remove_line_breaks(title)
-    # Remove line breaks from non-indented paragraphs in the body.
-    paragraphs = []
-    for paragraph in paragraph_split(body):
-        if not paragraph[:1].isspace():
-            paragraph = remove_line_breaks(paragraph)
-        paragraphs.append(paragraph)
-    # Rejoin the paragraphs, normalising on newline.
-    body = (newline + newline).join(
-        paragraph.replace("\r\n", newline).replace("\r", newline)
-        for paragraph in paragraphs)
+    # Normalise line-breaks on newline.
+    body = body.replace("\r\n", newline).replace("\r", newline)
     return title, body