Add skip_documentation parameter to NormalizeSeparators (#308)

Author: bhirsz

CHANGES.md

@@ -19,6 +19,16 @@ Keyword
     END
 ```
 
+### ``skip_documentation`` for NormalizeSeparators
+
+It is now possible to skip formatting suite, test case and keyword documentation with NormalizeSeparator transformer 
+by using ``skip_documentation`` parameter ([#300](https://github.com/MarketSquare/robotframework-tidy/issues/300)):
+
+```
+robotidy --configure NormalizeSeparators:skip_documentation=True src
+```
+
+
 ## 2.3
 
 ### Prettified output

docs/source/requirements.txt

@@ -1,2 +1,2 @@
-sphinx-tabs==3.2.0
+sphinx-tabs==3.3.1
 sphinx-copybutton==0.3.3

docs/source/transformers/NormalizeSeparators.rst

@@ -126,6 +126,49 @@ Combine it with ``spacecount`` to set whitespace separately for indent and separ
                 Keyword With  ${var}
             END
 
+Formatting documentation
+--------------------------
+
+Documentation is formatted by default. To disable formatting the separators inside documentation, and to only format
+indentation, set ``skip_documentation`` to ``True``::
+
+    robotidy --configure NormalizeSeparators:skip_documentation=True src
+
+.. tabs::
+
+    .. code-tab:: robotframework Before
+
+        TEST_TC
+            [Argument]    ${a}    ${long_arg}
+            [Documentation]     Test Doc.
+            ...
+            ...    Arguments:
+            ...    a:               Argument A
+            ...    long_arg:        Argument long_arg.
+           Test Case Body
+
+    .. code-tab:: robotframework skip_documentation=False (default)
+
+        TEST_TC
+            [Argument]    ${a}    ${long_arg}
+            [Documentation]     Test Doc.
+            ...
+            ...    Arguments:
+            ...    a:    Argument A
+            ...    long_arg:    Argument long_arg.
+           Test Case Body
+
+    .. code-tab:: robotframework skip_documentation=True
+
+        TEST_TC
+            [Argument]    ${a}    ${long_arg}
+            [Documentation]     Test Doc.
+            ...
+            ...    Arguments:
+            ...    a:               Argument A
+            ...    long_arg:        Argument long_arg.
+           Test Case Body
+
 Ignored sections
 ---------------
 

noxfile.py

@@ -19,21 +19,21 @@ def install_doc_deps(session, robot_major_ver):
 
 
 @nox.session(python=UNIT_TEST_PYTHON_VERSIONS)
-@nox.parametrize('robot_version', ["stable4", "stable5"])
+@nox.parametrize("robot_version", ["stable4", "stable5"])
 def unit(session, robot_version):
     install_dev_deps(session, robot_version)
-    session.run('pytest', 'tests')
+    session.run("pytest", "tests")
 
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def coverage(session):
     install_dev_deps(session, "stable5")
     session.install("coverage")
-    session.run('coverage', 'run', '-m', 'pytest')
-    session.run('coverage', 'html')
+    session.run("coverage", "run", "-m", "pytest")
+    session.run("coverage", "html")
 
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def docs(session):
     install_doc_deps(session, "stable5")
-    session.run('sphinx-build', '-b', 'html', 'docs/source', 'docs/_build/')
+    session.run("sphinx-build", "-b", "html", "docs/source", "docs/_build/")

robotidy/transformers/NormalizeSeparators.py

@@ -21,12 +21,15 @@ class NormalizeSeparators(ModelTransformer):
     You can decide which sections should be transformed by configuring
     ``sections = comments,settings,variables,keywords,testcases`` param.
 
+    To not format documentation configure ``skip_documentation`` to ``True``.
+
     Supports global formatting params: ``--startline`` and ``--endline``.
     """
 
-    def __init__(self, sections: str = None):
+    def __init__(self, sections: str = None, skip_documentation: bool = False):
         self.indent = 0
         self.sections = self.parse_sections(sections)
+        self.skip_documentation = skip_documentation
         self.is_inline = False
 
     def parse_sections(self, sections):
@@ -129,12 +132,18 @@ def visit_If(self, node):
         self.is_inline = False
         return node
 
+    def visit_Documentation(self, doc):  # noqa
+        if self.skip_documentation:
+            has_pipes = doc.tokens[0].value.startswith("|")
+            return self._handle_spaces(doc, has_pipes, only_indent=True)
+        return self.visit_Statement(doc)
+
     @skip_if_disabled
     def visit_Statement(self, statement):  # noqa
         has_pipes = statement.tokens[0].value.startswith("|")
         return self._handle_spaces(statement, has_pipes)
 
-    def _handle_spaces(self, statement, has_pipes):
+    def _handle_spaces(self, statement, has_pipes, only_indent=False):
         new_tokens = []
         for line in statement.lines:
             prev_sep = False
@@ -145,7 +154,7 @@ def _handle_spaces(self, statement, has_pipes):
                     prev_sep = True
                     if index == 0:
                         token.value = self.formatting_config.indent * self.indent
-                    else:
+                    elif not only_indent:
                         token.value = self.formatting_config.separator
                 else:
                     prev_sep = False

setup.py

@@ -59,6 +59,8 @@
         "doc": [
             "sphinx_rtd_theme",
             "sphinx",
+            "sphinx-tabs==3.3.1",
+            "sphinx-copybutton==0.3.3",
         ],
     },
     entry_points={"console_scripts": ["robotidy=robotidy.cli:cli"]},

tests/atest/transformers/NormalizeSeparators/expected/comment_keywords.robot

@@ -17,6 +17,7 @@ ${var}     3
 *** Test Cases ***
 Test case
   [Setup]  Keyword
+  [Documentation]  First word   Second word
    Keyword  with  arg
    ...  and  multi  lines
      [Teardown]          Keyword
@@ -33,6 +34,8 @@ Test case with structures
 Keyword
 Another Keyword
     [Arguments]    ${arg}
+    [Documentation]    First word    Second word
+    ...    Third.
     Should Be Equal    1
     ...    ${arg}
     IF    ${condition}

tests/atest/transformers/NormalizeSeparators/expected/comments_settings_variable_keywords_testcases.robot

@@ -17,6 +17,7 @@ ${var}    3
 *** Test Cases ***
 Test case
     [Setup]    Keyword
+    [Documentation]    First word    Second word
     Keyword    with    arg
     ...    and    multi    lines
     [Teardown]    Keyword
@@ -33,6 +34,8 @@ Test case with structures
 Keyword
 Another Keyword
     [Arguments]    ${arg}
+    [Documentation]    First word    Second word
+    ...    Third.
     Should Be Equal    1
     ...    ${arg}
     IF    ${condition}

tests/atest/transformers/NormalizeSeparators/expected/comments_settings_variables.robot

@@ -17,6 +17,7 @@ ${var}    3
 *** Test Cases ***
 Test case
   [Setup]  Keyword
+  [Documentation]  First word   Second word
    Keyword  with  arg
    ...  and  multi  lines
      [Teardown]          Keyword
@@ -33,6 +34,8 @@ Test case with structures
 Keyword
 Another Keyword
           [Arguments]  ${arg}
+          [Documentation]  First word   Second word
+         ...  Third.
        Should Be Equal  1
        ...  ${arg}
    IF  ${condition}

tests/atest/transformers/NormalizeSeparators/expected/skip_documentation.robot

@@ -0,0 +1,50 @@
+# this is    comment
+
+*** Settings ***
+Library    library.py    WITH NAME    alias
+
+Force Tags    tag
+...    tag
+
+Documentation  doc
+...      multi
+...  line
+
+*** Variables ***
+${var}    3
+ ${var2}    4
+
+*** Test Cases ***
+Test case
+    [Setup]    Keyword
+    [Documentation]  First word   Second word
+    Keyword    with    arg
+    ...    and    multi    lines
+    [Teardown]    Keyword
+
+Test case with structures
+    FOR    ${variable}    IN    1    2
+        Keyword
+        IF    ${condition}
+            Log    ${stuff}    console=True
+        END
+    END
+
+*** Keywords ***
+Keyword
+Another Keyword
+    [Arguments]    ${arg}
+    [Documentation]  First word   Second word
+    ...  Third.
+    Should Be Equal    1
+    ...    ${arg}
+    IF    ${condition}
+        FOR    ${v}    IN RANGE    10
+            Keyword
+        END
+    END
+
+Keyword With Tabulators
+    Keyword
+    ...    2
+    ...    ${arg}