Minor improvements to usage message reformatting

Author: xolox

humanfriendly/__init__.py

@@ -37,7 +37,7 @@
 from humanfriendly.compat import is_string
 
 # Semi-standard module versioning.
-__version__ = '1.44.6'
+__version__ = '1.44.7'
 
 # Spinners are redrawn at most this many seconds.
 minimum_spinner_interval = 0.2

humanfriendly/tests.py

@@ -4,7 +4,7 @@
 # Tests for the `humanfriendly' package.
 #
 # Author: Peter Odding <peter.odding@paylogic.eu>
-# Last Change: March 20, 2016
+# Last Change: April 21, 2016
 # URL: https://humanfriendly.readthedocs.org
 
 """Test suite for the `humanfriendly` package."""
@@ -748,13 +748,13 @@ def test_render_usage(self):
               $ echo test
               test
         """))
-        assert all(token in render_usage("""
+        assert all(token in render_usage(dedent("""
             Supported options:
 
               -n, --dry-run
 
                 Don't change anything.
-        """) for token in ('`-n`', '`--dry-run`'))
+        """)) for token in ('`-n`', '`--dry-run`'))
 
     def test_sphinx_customizations(self):
         """Test the :mod:`humanfriendly.sphinx` module."""

humanfriendly/usage.py

@@ -308,17 +308,29 @@ def render_paragraph(paragraph, meta_variables):
         return "**%s**" % paragraph
     # Reformat shell transcripts into code blocks.
     if re.match(r'^\s*\$\s+\S', paragraph):
-        lines = ['   %s' % line for line in paragraph.splitlines()]
+        # Split the paragraph into lines.
+        lines = paragraph.splitlines()
+        # Check if the paragraph is already indented.
+        if not paragraph[0].isspace():
+            # If the paragraph isn't already indented we'll indent it now.
+            lines = ['  %s' % line for line in lines]
         lines.insert(0, '.. code-block:: sh')
         lines.insert(1, '')
         return "\n".join(lines)
-    # Change `quoting' so it doesn't trip up DocUtils.
-    paragraph = re.sub("`(.+?)'", r'"\1"', paragraph)
-    # Escape asterisks.
-    paragraph = paragraph.replace('*', r'\*')
-    # Reformat inline tokens.
-    return replace_special_tokens(paragraph, meta_variables,
-                                  lambda token: '``%s``' % token)
+    # The following reformatting applies only to paragraphs which are not
+    # indented. Yes this is a hack - for now we assume that indented paragraphs
+    # are code blocks, even though this assumption can be wrong.
+    if not paragraph[0].isspace():
+        # Change UNIX style `quoting' so it doesn't trip up DocUtils.
+        paragraph = re.sub("`(.+?)'", r'"\1"', paragraph)
+        # Escape asterisks.
+        paragraph = paragraph.replace('*', r'\*')
+        # Reformat inline tokens.
+        paragraph = replace_special_tokens(
+            paragraph, meta_variables,
+            lambda token: '``%s``' % token,
+        )
+    return paragraph
 
 
 def replace_special_tokens(text, meta_variables, replace_fn):