Upgrade styler to better handle lists (#9423)

* Add missing lines before a new list.

* Update doc styler and restyle some files.

* Fix docstrings of LED and Longformer

utils/style_doc.py

@@ -42,7 +42,7 @@ DOC_SPECIAL_WORD = [
 # Matches any declaration of textual block, like `.. note::`. (ignore case to avoid writing all versions in the list)
 _re_textual_blocks = re.compile(r"^\s*\.\.\s+(" + "|".join(TEXTUAL_BLOCKS) + r")\s*::\s*$", re.IGNORECASE)
 # Matches list introduction in rst.
-_re_list = re.compile(r"^(\s*-\s+|\s*\*\s+|\s*\d+.\s+)")
+_re_list = re.compile(r"^(\s*-\s+|\s*\*\s+|\s*\d+\.\s+)")
 # Matches the indent in a line.
 _re_indent = re.compile(r"^(\s*)\S")
 # Matches a table declaration in rst.
@@ -355,10 +355,34 @@ rst_styler = CodeStyler()
 doc_styler = DocstringStyler()
 
 
+def _add_new_lines_before_list(text):
+    """Add a new empty line before a list begins."""
+    lines = text.split("\n")
+    new_lines = []
+    in_list = False
+    for idx, line in enumerate(lines):
+        # Detect if the line is the start of a new list.
+        if _re_list.search(line) is not None and not in_list:
+            current_indent = get_indent(line)
+            in_list = True
+            # If the line before is non empty, add an extra new line.
+            if idx > 0 and len(lines[idx - 1]) != 0:
+                new_lines.append("")
+        # Detect if we're out of the current list.
+        if in_list and not line.startswith(current_indent) and _re_list.search(line) is None:
+            in_list = False
+        new_lines.append(line)
+    return "\n".join(new_lines)
+
+
 def style_rst_file(doc_file, max_len=119, check_only=False):
     """ Style one rst file `doc_file` to `max_len`."""
     with open(doc_file, "r", encoding="utf-8", newline="\n") as f:
         doc = f.read()
+
+    # Add missing new lines before lists
+    doc = _add_new_lines_before_list(doc)
+    # Style
     clean_doc = rst_styler.style(doc, max_len=max_len)
 
     diff = clean_doc != doc
@@ -391,6 +415,8 @@ def style_docstring(docstring, max_len=119):
 
     # Add missing new lines before Args/Returns etc.
     docstring = _re_any_doc_special_word.sub(r"\n\n\1\2\3\n", docstring)
+    # Add missing new lines before lists
+    docstring = _add_new_lines_before_list(docstring)
     # Style
     styled_doc = doc_styler.style(docstring, max_len=max_len, min_indent=indent)