Fix typos, refactor documentation and add missing release notes

docs/releasenotes/unreleased/fixes.5.rst

@@ -0,0 +1,7 @@
+Typos in the documentation (#656, #588)
+---------------------------------------
+
+Several typos were fixed in our documentation. Feel free to report any issue - to improve documentation for everyone!
+
+We have also reorganized some of the information in the documentation to make it easier to find information. For
+example disablers are now in the separate page instead of quickstart page.

docs/releasenotes/unreleased/other.3.rst

@@ -0,0 +1,9 @@
+Output of number of skipped files in run summary (#661)
+-------------------------------------------------------
+
+Skipped files are now reported separately in the run summary::
+
+    > robotidy read_only_file.robot
+    0 files reformatted, 0 files left unchanged. 1 file skipped.
+
+Thanks @kottenko for contributing PR.

docs/releasenotes/unreleased/other.4.rst

@@ -0,0 +1,7 @@
+Errors outputted to error stream (#664)
+---------------------------------------
+
+Configuration or file errors use now error stream for reporting issues instead of standard output. It makes it easy
+to notice issues when running Robotidy on Unix systems.
+
+Thanks @kottenko for contributing PR.

docs/source/configuration/disablers.rst

@@ -0,0 +1,113 @@
+.. _disablers:
+
+Disablers
+=========
+
+.. rubric:: Disablers
+
+You can disable formatting of statement or in span of lines using ``# robotidy: off`` marker.
+
+To skip the formatting for one statement:
+
+.. code-block:: robotframework
+
+    Keyword That Is Longer Than Allowed Line Length  ${arg}  # robotidy: off
+
+To skip multiple lines:
+
+.. code-block:: robotframework
+
+    *** Test Cases ***
+    Test that will be formatted
+        Step
+
+    # robotidy: off
+    Test that will not be formatted
+        Step
+
+    # robotidy: on
+    Another test that will be formatted
+        Step
+
+You can also disable the formatting in the whole section if you put ``# robotidy: off`` in the section header:
+
+.. code-block:: robotframework
+
+    *** Test Cases ***
+    Formatted
+        Step
+
+    *** Keywords ***  # robotidy: off
+    Not Formatted
+        Step
+
+Enable formatting again
+------------------------
+
+``# robotidy: on`` marker is used to enable the formatting again - but is not required. ``# robotidy: off`` will disable
+the formatting to the end of the current block:
+
+.. code-block:: robotframework
+
+    *** Keywords ***
+    Keyword
+        Keyword That Is Formatted
+        IF    $condition
+            Formatted
+        ELSE
+            Formatted
+            # robotidy: off
+            Not Formatted
+            WHILE    $condition
+                Not Formatted
+            END
+        END
+        Formatted
+
+Disable only selected transformers
+-----------------------------------
+
+It is possible to disable only selected transformers by passing their names to disabler in comma separated list:
+
+.. code-block:: robotframework
+
+    *** Test Cases ***
+    Formatted Partially
+        Step
+        ...    ${arg}  # robotidy: off=AlignTestCasesSection,NormalizeSeparators
+        Step 2
+
+    *** Keywords ***  # robotidy: off = NormalizeNewLines
+    Not Formatted
+        Step
+
+Disable formatting of whole file
+--------------------------------
+
+It's possible to disable the formatting in whole file by putting ``# robotidy: off`` on the first line:
+
+.. code-block:: robotframework
+
+    # robotidy: off
+    *** Settings ***
+    Library    Collections
+
+File disablers can be also placed in first comment section in the file:
+
+.. code-block:: robotframework
+
+    *** Comments ***
+    # Following line disables formatting this file with Robotidy
+    # robotidy: off
+
+    *** Settings ***
+    Library    Collections
+
+File disablers supports also disabling selected transformers:
+
+.. code-block:: robotframework
+
+    # robotidy: off = RenameVariables
+
+    *** Settings ***
+    Library    Collections

docs/source/configuration/index.rst

@@ -9,6 +9,7 @@ Configuration
 
    config_file
    configuring_transformers
+   disablers
    skip_formatting
 
 Behaviour of *robotidy* can be changed through global options or by configuring specific transformer.
@@ -23,9 +24,9 @@ To list *robotidy* command line options run::
 
 .. rubric:: Ignored paths
 
-Robotidy reads and ignores paths from ``.gitignore`` and ``--exclude``. You can overwrite default excludes by using
-``--exclude`` option. If you want to exclude additional paths on top of those from ``--exclude`` and ``.gitignore`` use
-``--extend-exclude`` with pattern::
+Robotidy reads and ignores paths from ``.gitignore`` file and ``--exclude`` option. You can overwrite default excludes
+by using ``--exclude`` option. If you want to exclude additional paths on top of those from ``--exclude`` and
+``.gitignore`` use ``--extend-exclude`` with pattern::
 
     robotidy --extend-exclude skip_me.robot|some_dir/* .
 
@@ -85,86 +86,3 @@ Language header in the file is supported by default::
 
 
 Custom language file is currently not supported.
-
-.. _disablers:
-
-.. rubric:: Disablers
-
-You can disable formatting in Robot Framework statement or in span of lines using ``# robotidy: off`` marker.
-
-To skip the formatting for one statement:
-
-.. code-block:: robotframework
-
-    Keyword That Is Longer Than Allowed Line Length  ${arg}  # robotidy: off
-
-To skip multiple lines:
-
-.. code-block:: robotframework
-
-    *** Test Cases ***
-    Test that will be formatted
-        Step
-
-    # robotidy: off
-    Test that will not be formatted
-        Step
-
-    # robotidy: on
-    Another test that will be formatted
-        Step
-
-
-``# robotidy: on`` marker is used to enable the formatting again - but is not required. ``# robotidy: off`` will disable
-the formatting to the end of the current block:
-
-.. code-block:: robotframework
-
-    *** Keywords ***
-    Keyword
-        Keyword That Is Formatted
-        IF    $condition
-            Formatted
-        ELSE
-            Formatted
-            # robotidy: off
-            Not Formatted
-            WHILE    $condition
-                Not Formatted
-            END
-        END
-        Formatted
-
-It's possible to disable the formatting in whole file by putting ``# robotidy: off`` on first line:
-
-.. code-block:: robotframework
-
-    # robotidy: off
-    *** Settings ***
-    Library    Collections
-
-You can also disable the formatting in the whole section if you put ``# robotidy: off`` in the section header:
-
-.. code-block:: robotframework
-
-    *** Test Cases ***
-    Formatted
-        Step
-
-    *** Keywords ***  # robotidy: off
-    Not Formatted
-        Step
-
-It is possible to disable only selected transformers by passing their names to disabler in comma separated list:
-
-.. code-block:: robotframework
-
-    *** Test Cases ***
-    Formatted Partially
-        Step
-        ...    ${arg}  # robotidy: off=AlignTestCasesSection,NormalizeSeparators
-        Step 2
-
-    *** Keywords ***  # robotidy: off = NormalizeNewLines
-    Not Formatted
-        Step

docs/source/configuration/skip_formatting.rst

@@ -4,7 +4,9 @@ Skip formatting
 ================
 .. rubric:: Skip formatting
 
-It is possible to skip formatting on code that matches given criteria.
+It is possible to skip formatting on code that matches given criteria. Skip options apply to all instances of the
+given code - for example it is possible to skip formatting on all documentation. If you want to disable formatting
+on specific lines, see :ref:`disablers`.
 
 To see what types are possible to skip, see ``Skip formatting`` sections in each transformer documentation.
 

docs/source/quickstart.rst

@@ -2,6 +2,7 @@
 
 Quickstart
 ===========
+
 `Robotidy` is easy to use and you can do it just by running::
 
     robotidy path/to/file_or_directory.robot
@@ -97,7 +98,7 @@ To see list of transformers included with `Robotidy` use ``--list``::
 
     Non-default transformers needs to be selected explicitly with --transform or configured with param `enabled=True`.
 
-Pass optional value ``enabled`` or ``disabled`` to filter our output by the status of the transformer::
+Pass optional value ``enabled`` or ``disabled`` to filter out output by the status of the transformer::
 
     > robotidy --list disabled
                     Transformers
@@ -170,3 +171,24 @@ configuring ``lineseparator`` option:
 - windows: use Windows line endings (CRLF)
 - unix:    use Unix line endings (LF)
 - auto:    maintain existing line endings (uses what's used in the first line of the file)
+
+Rerun the transformation in place
+----------------------------------
+
+Because of high independence of each transformer, Robotidy runs them in specific order to obtain predictable results.
+But sometimes the subsequent transformer modifies the file to the point that it requires another run of Robotidy.
+Good example would be one transformer that replaces the deprecated syntax - but new syntax is inserted using standard
+whitespace. If there is transformer that aligns this whitespace according to special rules
+(like ``AlignKeywordsSection``) we need to run Robotidy again to format this whitespace.
+
+This could be inconvenient in some cases where user had to rerun Robotidy without knowing why. That's why Robotidy
+now has option ``reruns`` that allows to define limit of how many extra reruns Robotidy can perform if the
+file keeps changing after the transformation. The default is ``0``. Recommended value is ``3``
+although in vast majority of cases one extra run should suffice (and only in cases described above).
+
+Example usage::
+
+    > robotidy --reruns 3 --diff test.robot
+
+Note that if you enable it, it can double the execution time of Robotidy (if the file was modified, it will be
+transformed again to check if next transformation does not further modify the file).

docs/source/transformers/AlignTestCasesSection.rst

@@ -70,11 +70,11 @@ Widths
 The column width is configurable via ``widths`` parameter. The default value is ``24``.
 It's possible to configure width of the several columns (using comma separated list of integers)::
 
-    robotidy -c AlignKeywordsSection:widths=20
+    robotidy -c AlignTestCasesSection:widths=20
 
 ::
 
-    robotidy -c AlignKeywordsSection:widths=10,10,24,30
+    robotidy -c AlignTestCasesSection:widths=10,10,24,30
 
 The last width will be used for the remaining columns. In previous example we configured widths for the 4 columns.
 The last width (``30``) will be used for 5th, 6th.. and following columns.
@@ -173,7 +173,7 @@ does not fit in the column.
 
 Below example was run with config::
 
-    robotidy -c AlignKeywordsSection:enabled=True:handle_too_long=compact_overflow:widths=24,28,20 src.robot
+    robotidy -c AlignTestCasesSection:enabled=True:handle_too_long=compact_overflow:widths=24,28,20 src.robot
 
 .. tab-set::