Documentation formatting: Allow splitting list items into multiple lines by indenting continuing lines

pekkaklarck · pekkaklarck · commit ebeb9e991572 · 2012-07-12T01:51:21.000+03:00
Update issue 1174
Status: Done
Owner: pekka.klarck
Implemented, tested, and documented.
diff --git a/doc/userguide/src/Appendices/DocumentationFormatting.txt b/doc/userguide/src/Appendices/DocumentationFormatting.txt
@@ -302,12 +302,14 @@ example would be formatted like this in HTML:
 Lists
 ~~~~~
 
-Lists are created by starting a line with a hyphen and space ('- ').
-An empty line or line not starting with '- ' ends the list::
+Lists are created by starting a line with a hyphen and space ('- '). List items
+can be split into multiple lines by indenting continuing lines with one or more
+spaces. A line that does not start with '- ' and is not indented ends the list::
 
   Example:
   - a list item
-  - a second list item
+  - second list item
+    is continued
 
   This is outside the list.
 
@@ -319,14 +321,15 @@ The above documentation is formatted like this in HTML:
   <p>Example:</p>
   <ul>
     <li>a list item</li>
-    <li>a second list item</li>
+    <li>second list item is continued</li>
   </ul>
   <p>This is outside the list.</p>
   </div>
 
 .. note:: Support for formatting lists was added in 2.7.2. Prior to that,
           the same syntax prevented :prog:`libdoc` from combining lines to
-          paragraphs, though, so the end result was similar.
+          paragraphs, so the end result was similar. Support for splitting
+          list items into multiple lines was added in 2.7.4.
 
 Preformatted text
 ~~~~~~~~~~~~~~~~~
diff --git a/src/robot/htmldata/testdata/dir.suite/__init__.txt b/src/robot/htmldata/testdata/dir.suite/__init__.txt
@@ -14,6 +14,11 @@ Documentation  Documentation for the whole test suite. All this forms a single
 ...            regular line
 ...            | pre *formatted*
 ...            | \ \ content\t\with whitespaces
+...            ---
+...            - first list item
+...            - second list item
+...            \ is continued \
+...            using *two* different approaches
 Metadata       URL       http://robotframework.org
 Metadata       Image     http://code.google.com/p/robotframework/logo?ext.png
 Metadata       Formatting  *Bold* and _italics_
diff --git a/src/robot/utils/htmlformatters.py b/src/robot/utils/htmlformatters.py
@@ -119,12 +119,12 @@ def __init__(self):
 
     def format(self, text):
         for line in text.splitlines():
-            self._process_line(line.strip())
+            self._process_line(line)
         self._end_current()
         return '\n'.join(self._results)
 
     def _process_line(self, line):
-        if not line:
+        if not line.strip():
             self._end_current()
         elif self._current and self._current.handles(line):
             self._current.add(line)
@@ -145,12 +145,19 @@ def _find_formatter(self, line):
 
 
 class _BlockFormatter(object):
+    _strip_lines = True
 
     def __init__(self):
         self._lines = []
 
+    def handles(self, line):
+        return self._handles(line.strip() if self._strip_lines else line)
+
+    def _handles(self, line):
+        raise NotImplementedError
+
     def add(self, line):
-        self._lines.append(line)
+        self._lines.append(line.strip() if self._strip_lines else line)
 
     def end(self):
         result = self.format(self._lines)
@@ -164,7 +171,7 @@ def format(self, lines):
 class RulerFormatter(_BlockFormatter):
     _hr_matcher = re.compile('^-{3,}$').match
 
-    def handles(self, line):
+    def _handles(self, line):
         return not self._lines and self._hr_matcher(line)
 
     def format(self, lines):
@@ -178,22 +185,22 @@ def __init__(self, other_formatters):
         _BlockFormatter.__init__(self)
         self._other_formatters = other_formatters
 
-    def handles(self, line):
-        if any(formatter.handles(line) for formatter in self._other_formatters):
-            return False
-        if line:
-            return True
-        return not self._lines
+    def _handles(self, line):
+        return not any(other.handles(line)
+                       for other in self._other_formatters)
 
     def format(self, lines):
         return '<p>%s</p>' % self._format_line(' '.join(lines))
 
 
 class TableFormatter(_BlockFormatter):
-    handles = re.compile('^\| (.* |)\|$').match
+    _table_line = re.compile('^\| (.* |)\|$')
     _line_splitter = re.compile(' \|(?= )')
     _format_cell = LineFormatter().format
 
+    def _handles(self, line):
+        return self._table_line.match(line) is not None
+
     def format(self, lines):
         return self._format_table([self._split_to_cells(l) for l in lines])
 
@@ -215,7 +222,7 @@ def _format_table(self, rows):
 class PreformattedFormatter(_BlockFormatter):
     _format_line = LineFormatter().format
 
-    def handles(self, line):
+    def _handles(self, line):
         return line.startswith('| ') or line == '|'
 
     def format(self, lines):
@@ -224,12 +231,26 @@ def format(self, lines):
 
 
 class ListFormatter(_BlockFormatter):
+    _strip_lines = False
     _format_item = LineFormatter().format
 
-    def handles(self, line):
-        return line.startswith('- ')
+    def _handles(self, line):
+        return line.strip().startswith('- ') or \
+                line.startswith(' ') and self._lines
 
     def format(self, lines):
-        items = ['<li>%s</li>' % self._format_item(line[2:].strip())
-                 for line in lines]
+        items = ['<li>%s</li>' % self._format_item(line)
+                 for line in self._combine_lines(lines)]
         return '\n'.join(['<ul>'] + items + ['</ul>'])
+
+    def _combine_lines(self, lines):
+        current = []
+        for line in lines:
+            line = line.strip()
+            if not line.startswith('- '):
+                current.append(line)
+                continue
+            if current:
+                yield ' '.join(current)
+            current = [line[2:].strip()]
+        yield ' '.join(current)
diff --git a/utest/utils/test_markuputils.py b/utest/utils/test_markuputils.py
@@ -529,6 +529,21 @@ def test_list_with_formatted_content(self):
                       '<ul>\n<li><b>bold</b> text</li>\n<li><i>italic</i></li>\n'
                       '<li><a href="http://url">link</a></li>\n</ul>')
 
+    def test_indentation_can_be_used_to_continue_list_item(self):
+        assert_format('''
+  outside list
+- this item
+  continues
+  - 2nd item
+    continues
+ twice
+''', '''\
+<p>outside list</p>
+<ul>
+<li>this item continues</li>
+<li>2nd item continues twice</li>
+</ul>''')
+
     def test_lists_with_other_content_around(self):
         assert_format('''
 before
@@ -538,6 +553,8 @@ def test_lists_with_other_content_around(self):
 
 - c
 - d
+  e
+  f
 
 ---
 ''',  '''\
@@ -549,7 +566,7 @@ def test_lists_with_other_content_around(self):
 <p>between</p>
 <ul>
 <li>c</li>
-<li>d</li>
+<li>d e f</li>
 </ul>
 <hr>''')
 
