Skip sections with --skip-sections option (#486)

Add --skip-sections option to several transformers. Allows to skip formatting of
selected sections.

This option is redudant with NormalizeSeparators "sections" options and it was
replaced by it.

Author: bhirsz

docs/releasenotes/3.6.0.rst docs/releasenotes/4.0.0.rstdocs/releasenotes/3.6.0.rst renamed to docs/releasenotes/4.0.0.rst

@@ -1,14 +1,16 @@
-Robotidy 3.6.0
+Robotidy 4.0.0
 =========================================
 
+Major release which contains multiple improvements for external transformers. There are also backward incompatible
+changes, including removing ``section`` option from ``NormalizeSeparators`` (replaced with ``skip_sections``).
 
 You can install the latest available version by running::
 
     pip install --upgrade robotframework-tidy
 
 or to install exactly this version::
 
-    pip install robotframework-tidy==3.6.0
+    pip install robotframework-tidy==4.0.0
 
 Rerun the transformation in place
 ----------------------------------
@@ -81,3 +83,36 @@ list in the ``__init__.py``::
         "TransformerA",
         "TransformerB"
     ]
+
+New skip option: --skip-sections #388 #475
+-------------------------------------------
+
+It is now possible to skip formatting of whole sections with new ``--skip-sections`` option.
+
+Currently supported in::
+
+    AddMissingEnd
+    DiscardEmptySections
+    NormalizeAssignments
+    NormalizeNewLines
+    NormalizeSectionHeaderName
+    NormalizeSeparators
+    SplitTooLongLine
+
+Support for other transformers can be added if needed.
+
+You can configure which section to skip using comma separated list of section names: settings,variables,testcases,tasks,keywords,comments.
+Like other skip options it can be used either for all transformers with ``--skip-sections``, or only for configured
+transformer::
+
+    > robotidy --configure DiscardEmptySections:skip_sections=variables src
+
+Since this option provides the same functionality as ``section`` argument in ``NormalizeSeparators``, the ``section``
+option was removed. Note that to replicate the same behaviour, you now need to list sections that you want to skip
+rather than the sections you want to format. For example following command::
+
+    > robotidy -c NormalizeSeparators:sections=settings,variables,testcases,comments src
+
+Is now equivalent of::
+
+    > robotidy -c NormalizeSeparators:skip_sections=keywords

docs/source/configuration/skip_formatting.rst

@@ -18,6 +18,7 @@ To see what types are possible to skip, see ``Skip formatting`` sections in each
 
 Skip documentation
 -------------------
+
 Flag that disables formatting of the documentation. Example usage::
 
     robotidy -c NormalizeSeparators:skip_documentation=True src
@@ -28,6 +29,7 @@ It is possible to use global flag to skip formatting for every transformer that
 
 Configuration file
 ~~~~~~~~~~~~~~~~~~~~
+
 Both options are configurable using configuration file (:ref:`config-file`).
 
 .. code-block:: toml
@@ -42,6 +44,7 @@ Both options are configurable using configuration file (:ref:`config-file`).
 
 Skip return values
 -------------------
+
 Flag that disables formatting of the return values (assignments). Example usage::
 
     robotidy -c AlignKeywordsSection:skip_return_values=True src
@@ -52,6 +55,7 @@ It is possible to use global flag to skip formatting for every transformer that
 
 Configuration file
 ~~~~~~~~~~~~~~~~~~~~
+
 Both options are configurable using configuration file (:ref:`config-file`).
 
 .. code-block:: toml
@@ -66,6 +70,7 @@ Both options are configurable using configuration file (:ref:`config-file`).
 
 Skip keyword call
 ------------------
+
 Comma-separated list of keyword call names that should not be formatted. Names will be
 normalized before search (spaces and underscores removed, lowercase).
 
@@ -81,6 +86,7 @@ It is possible to use global option to skip formatting for every transformer tha
 
 Configuration file
 ~~~~~~~~~~~~~~~~~~~~
+
 Both options are configurable using configuration file (:ref:`config-file`).
 
 .. code-block:: toml
@@ -98,6 +104,7 @@ Both options are configurable using configuration file (:ref:`config-file`).
 
 Skip keyword call pattern
 -------------------------
+
 Comma-separated list of keyword call name patterns that should not be formatted. The keyword names are not normalized.
 If you're using different case for the same keyword ("Keyword" and "keyword") or using both spaces and underscores, it is
 recommended to use proper regex flags to match it properly.
@@ -117,6 +124,7 @@ It is possible to use global option to skip formatting for every transformer tha
 
 Configuration file
 ~~~~~~~~~~~~~~~~~~~~
+
 Both options are configurable using configuration file (:ref:`config-file`).
 
 .. code-block:: toml
@@ -134,6 +142,7 @@ Both options are configurable using configuration file (:ref:`config-file`).
 
 Skip settings
 -------------------
+
 Flag that disables formatting of the settings. Example usage::
 
     robotidy -c AlignTestCasesSection:skip_settings=True src
@@ -157,6 +166,7 @@ Following types are possible to skip:
 
 Configuration file
 ~~~~~~~~~~~~~~~~~~~~
+
 Option is configurable using configuration file (:ref:`config-file`).
 
 Skip formatting of all settings:
@@ -185,6 +195,7 @@ Skip formatting of selected settings:
 
 Skip comments and block comments
 ---------------------------------
+
 Flag that disables formatting of the comments and block comments. Example usage::
 
     robotidy -c NormalizeSeparators:skip_comments=True src
@@ -219,3 +230,30 @@ Both options are configurable using configuration file (:ref:`config-file`).
     configure = [
         "NormalizeSeparators : skip_block_comments = False"
     ]
+
+.. _skip sections:
+
+Skip sections
+---------------
+
+Option that disables formatting of the selected settings. Example usage::
+
+    robotidy -c NormalizeSeparators:skip_sections=variables src
+
+It is possible to use global option to skip formatting for every transformer that supports it::
+
+    robotidy --skip-sections=keywords,testcases src
+
+Section names can be provided using comma separated list: settings,variables,testcases,keywords,comments.
+
+Configuration file
+~~~~~~~~~~~~~~~~~~~~
+Both options are configurable using configuration file (:ref:`config-file`).
+
+.. code-block:: toml
+
+    [tool.robotidy]
+    skip-sections = "comments"
+    configure = [
+        "NormalizeSeparators : skip_sections = tasks,keywords"
+    ]

docs/source/transformers/AddMissingEnd.rst

@@ -40,3 +40,13 @@ Add missing ``END`` token to FOR loops and IF statements.
                     END
                 END
                 Keyword
+
+Skip formatting
+----------------
+
+It is possible to use the following arguments to skip formatting of the code:
+
+- :ref:`skip sections`
+
+It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
+makes it easier to skip all instances of given type of the code.

docs/source/transformers/DiscardEmptySections.rst

@@ -98,3 +98,13 @@ section with only comments is always considered as non-empty::
 
             *** Comments ***
             # robocop: disable=all
+
+Skip formatting
+----------------
+
+It is possible to use the following arguments to skip formatting of the code:
+
+- :ref:`skip sections`
+
+It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
+makes it easier to skip all instances of given type of the code.

docs/source/transformers/NormalizeAssignments.rst

@@ -99,3 +99,13 @@ You can configure that behaviour to automatically add desired equal sign with ``
                 ${var} =  Keyword1
                 ${var} =   Keyword2
                 ${var} =    Keyword
+
+Skip formatting
+----------------
+
+It is possible to use the following arguments to skip formatting of the code:
+
+- :ref:`skip sections`
+
+It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
+makes it easier to skip all instances of given type of the code.

docs/source/transformers/NormalizeNewLines.rst

@@ -308,3 +308,13 @@ language marker:
 
 
             *** Ustawienia ***
+
+Skip formatting
+----------------
+
+It is possible to use the following arguments to skip formatting of the code:
+
+- :ref:`skip sections`
+
+It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
+makes it easier to skip all instances of given type of the code.

docs/source/transformers/NormalizeSectionHeaderName.rst

@@ -40,3 +40,13 @@ It is possible to upper case section header names by passing ``uppercase=True``
         .. code:: robotframework
 
             *** SETTINGS ***
+
+Skip formatting
+----------------
+
+It is possible to use the following arguments to skip formatting of the code:
+
+- :ref:`skip sections`
+
+It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
+makes it easier to skip all instances of given type of the code.

docs/source/transformers/NormalizeSeparators.rst

@@ -146,6 +146,7 @@ It is possible to use the following arguments to skip formatting of the code:
 - :ref:`skip keyword call`
 - :ref:`skip keyword call pattern`
 - :ref:`skip comments`
+- :ref:`skip sections`
 
 Documentation is formatted by default. To disable formatting the separators inside documentation, and to only format
 indentation, set ``skip_documentation`` to ``True``::
@@ -193,38 +194,12 @@ indentation, set ``skip_documentation`` to ``True``::
                 ...    long_arg:        Argument long_arg.
                Test Case Body
 
-Ignored sections
-------------------
-
-You can decide which sections should be transformed by configuring
-``sections = comments,settings,variables,keywords,testcases`` param::
-
-    robotidy --configure NormalizeSeparators:sections=variables src
-
-.. tab-set::
-
-    .. tab-item:: Before
-
-        .. code:: robotframework
-
-            *** Settings ***
-            Library  library.py  WITH NAME          alias
-
-            Force Tags           tag
-            ...   tag
-
-            *** Variables ***
-            ${var}  1  # only this section will be transformed
-
-    .. tab-item:: After
-
-        .. code:: robotframework
+Skip formatting
+----------------
 
-            *** Settings ***
-            Library  library.py  WITH NAME          alias
+It is possible to use the following arguments to skip formatting of the code:
 
-            Force Tags           tag
-            ...   tag
+- :ref:`skip sections`
 
-            *** Variables ***
-            ${var}    1    # only this section will be transformed
+It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
+makes it easier to skip all instances of given type of the code.

docs/source/transformers/SplitTooLongLine.rst

@@ -202,6 +202,7 @@ It is possible to use the following arguments to skip formatting of the code:
 - :ref:`skip keyword call pattern`
 - :ref:`skip settings`
 - :ref:`skip comments`
+- :ref:`skip sections`
 
 It is also possible to use disablers (:ref:`disablers`) but ``skip`` option
 makes it easier to skip all instances of given type of the code.

robotidy/api.py

@@ -9,6 +9,8 @@
 
 
 def get_skip_config(config):
+    # TODO: Improve it
+    skip_comments = config.get("skip_comments", False)
     skip_documentation = config.get("skip_documentation", False)
     skip_return_values = config.get("skip_return_values", False)
     skip_keyword_call = config.get("skip_keyword_call", [])
@@ -21,6 +23,8 @@ def get_skip_config(config):
     skip_timeout = config.get("skip_timeout", False)
     skip_return = config.get("skip_return", False)
     skip_tags = config.get("skip_tags", False)
+    skip_sections = config.get("skip_sections", "")
+    skip_block_comments = config.get("skip_block_comments", False)
     return skip.SkipConfig(
         documentation=skip_documentation,
         return_values=skip_return_values,
@@ -34,6 +38,9 @@ def get_skip_config(config):
         timeout=skip_timeout,
         return_statement=skip_return,
         tags=skip_tags,
+        comments=skip_comments,
+        block_comments=skip_block_comments,
+        sections=skip_sections,
     )