Rules documentation improvements (#2542)

* Rules documentation improvements

* Better wording

* Remove noqa

* Better line

* Better comments

* Remove unnecessary comment

* Remove another noqa which might not be needed

* Add back noqa

* Apply suggestions from code review

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L007.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L009.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L009.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L015.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L017.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L019.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L052.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Update src/sqlfluff/rules/L059.py

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

* Review feedback

* Fix line

* Better docs for L036

* Add explanation for rules

* More explanation for L031

* Remove initial explanation

* Rule L029 explanation

* Few more minor tweaks

* Comment update

Co-authored-by: Barry Hart <barrywhart@yahoo.com>

docs/source/inthewild.rst

@@ -53,4 +53,4 @@ Just add a section below by raising a PR on GitHub by
   `GitHub Actions workflow <https://github.com/sqlfluff/sqlfluff-github-actions/tree/main/menu_of_workflows/surfline>`_
   contributed by Greg Clunies, with annotations on pull requests to make it
   easy for contributors to see where their SQL has failed any rules. See an
-  `example pull request with SQLFLuff annotations <https://github.com/brooklyn-data/dbt_artifacts/pull/74/files>`_.
+  `example pull request with SQLFluff annotations <https://github.com/brooklyn-data/dbt_artifacts/pull/74/files>`_.

docs/source/rules.rst

@@ -38,7 +38,14 @@ ignore templating (``TMP``) & parsing (``PRS``) errors.
 
 .. code-block:: sql
 
-   WHERE dt >= DATE_ADD(CURRENT_DATE(), INTERVAL -2 DAY) -- noqa: PRS
+   WHERE
+     col1 = 2 AND
+     dt >= DATE_ADD(CURRENT_DATE(), INTERVAL -2 DAY) -- noqa: PRS
+
+.. note::
+   It should be noted that ignoring ``TMP`` and ``PRS`` errors can lead to
+   incorrect ``sqlfluff lint`` and ``sqfluff fix`` results as `SQLFluff` can
+   misinterpret the SQL being analysed.
 
 Should the need arise, not specifying specific rules to ignore will ignore
 all rules on the given line.

plugins/sqlfluff-plugin-example/src/example/rules.py

@@ -45,8 +45,9 @@ def get_configs_info() -> dict:
 class Rule_Example_L001(BaseRule):
     """ORDER BY on these columns is forbidden!
 
-    | **Anti-pattern**
-    | Using ORDER BY one some forbidden columns.
+    **Anti-pattern**
+
+    Using ``ORDER BY`` one some forbidden columns.
 
     .. code-block:: sql
 
@@ -56,8 +57,9 @@ class Rule_Example_L001(BaseRule):
             bar,
             baz
 
-    | **Best practice**
-    | Do not order by these columns.
+    **Best practice**
+
+    Do not order by these columns.
 
     .. code-block:: sql
 

src/sqlfluff/core/rules/config_info.py

@@ -64,7 +64,7 @@
         "validation": ["consistent", "upper", "lower", "pascal", "capitalise"],
         "definition": (
             "The capitalisation policy to enforce, extended with PascalCase. "
-            "This is separate from capitalisation_policy as it should not be "
+            "This is separate from ``capitalisation_policy`` as it should not be "
             "applied to keywords."
         ),
     },
@@ -117,7 +117,7 @@
         "definition": (
             "Should final semi-colons be required? "
             "(N.B. forcing trailing semi-colons is not recommended for dbt users "
-            "as it can cause issues when wrapping the query within other SQL queries)"
+            "as it can cause issues when wrapping the query within other SQL queries)."
         ),
     },
     "group_by_and_order_by_style": {
@@ -146,7 +146,7 @@
     },
     "blocked_words": {
         "definition": (
-            "Optional comma-separated list of blocked words which should not be used "
+            "Optional, comma-separated list of blocked words which should not be used "
             "in statements."
         ),
     },

src/sqlfluff/core/rules/doc_decorators.py

@@ -4,7 +4,7 @@
 from sqlfluff.core.rules.base import rules_logger  # noqa
 
 
-FIX_COMPATIBLE = "    ``sqlfluff fix`` compatible."
+FIX_COMPATIBLE = "    This rule is ``sqlfluff fix`` compatible."
 
 
 def document_fix_compatible(cls):
@@ -36,7 +36,7 @@ def document_configuration(cls, ruleset="std"):
             )
         )
 
-    config_doc = "\n    | **Configuration**"
+    config_doc = "\n    **Configuration**\n"
     try:
         for keyword in sorted(cls.config_keywords):
             try:
@@ -46,12 +46,15 @@ def document_configuration(cls, ruleset="std"):
                     "Config value {!r} for rule {} is not configured in "
                     "`config_info`.".format(keyword, cls.__name__)
                 )
-            config_doc += "\n    |     `{}`: {}".format(
-                keyword, info_dict["definition"]
-            )
+            config_doc += "\n    * ``{}``: {}".format(keyword, info_dict["definition"])
+            if (
+                config_doc[-1] != "."
+                and config_doc[-1] != "?"
+                and config_doc[-1] != "\n"
+            ):
+                config_doc += "."
             if "validation" in info_dict:
                 config_doc += " Must be one of ``{}``.".format(info_dict["validation"])
-            config_doc += "\n    |"
     except AttributeError:
         rules_logger.info(f"No config_keywords defined for {cls.__name__}")
         return cls
@@ -64,3 +67,8 @@ def document_configuration(cls, ruleset="std"):
 
     cls.__doc__ = cls.__doc__.replace(end_of_class_description, "\n" + config_doc, 1)
     return cls
+
+
+def is_configurable(cls) -> bool:
+    """Return whether the rule is documented as fixable."""
+    return "**Configuration**" in cls.__doc__

src/sqlfluff/rules/L001.py

@@ -8,8 +8,9 @@
 class Rule_L001(BaseRule):
     """Unnecessary trailing whitespace.
 
-    | **Anti-pattern**
-    | The • character represents a space.
+    **Anti-pattern**
+
+    The ``•`` character represents a space.
 
     .. code-block:: sql
        :force:
@@ -18,8 +19,9 @@ class Rule_L001(BaseRule):
             a
         FROM foo••
 
-    | **Best practice**
-    | Remove trailing spaces.
+    **Best practice**
+
+    Remove trailing spaces.
 
     .. code-block:: sql
 

src/sqlfluff/rules/L002.py

@@ -16,9 +16,10 @@ class Rule_L002(BaseRule):
     This rule will fail if a single section of whitespace
     contains both tabs and spaces.
 
-    | **Anti-pattern**
-    | The • character represents a space and the → character represents a tab.
-    | In this example, the second line contains two spaces and one tab.
+    **Anti-pattern**
+
+    The ``•`` character represents a space and the ``→`` character represents a tab.
+    In this example, the second line contains two spaces and one tab.
 
     .. code-block:: sql
        :force:
@@ -27,8 +28,9 @@ class Rule_L002(BaseRule):
         ••→a
         FROM foo
 
-    | **Best practice**
-    | Change the line to use spaces only.
+    **Best practice**
+
+    Change the line to use spaces only.
 
     .. code-block:: sql
        :force:

src/sqlfluff/rules/L003.py

@@ -17,13 +17,10 @@
 class Rule_L003(BaseRule):
     """Indentation not consistent with previous lines.
 
-    Note:
-        This rule used to be _"Indentation length is not a multiple
-        of `tab_space_size`"_, but was changed to be much smarter.
+    **Anti-pattern**
 
-    | **Anti-pattern**
-    | The • character represents a space.
-    | In this example, the third line contains five spaces instead of four.
+    The ``•`` character represents a space.
+    In this example, the third line contains five spaces instead of four.
 
     .. code-block:: sql
        :force:
@@ -34,8 +31,9 @@ class Rule_L003(BaseRule):
         FROM foo
 
 
-    | **Best practice**
-    | Change the indentation to use a multiple of four spaces.
+    **Best practice**
+
+    Change the indentation to use a multiple of four spaces.
 
     .. code-block:: sql
        :force:

src/sqlfluff/rules/L004.py

@@ -12,13 +12,16 @@
 class Rule_L004(BaseRule):
     """Incorrect indentation type.
 
-    Note 1: spaces are only fixed to tabs if the number of spaces in the
-    indent is an integer multiple of the tab_space_size config.
-    Note 2: fixes are only applied to indents at the start of a line. Indents
-    after other text on the same line are not fixed.
+    .. note::
+       Note 1: spaces are only fixed to tabs if the number of spaces in the
+       indent is an integer multiple of the ``tab_space_size`` config.
 
-    | **Anti-pattern**
-    | Using tabs instead of spaces when indent_unit config set to spaces (default).
+       Note 2: fixes are only applied to indents at the start of a line. Indents
+       after other text on the same line are not fixed.
+
+    **Anti-pattern**
+
+    Using tabs instead of spaces when ``indent_unit`` config set to ``space`` (default).
 
     .. code-block:: sql
        :force:
@@ -28,8 +31,9 @@ class Rule_L004(BaseRule):
         →   b
         from foo
 
-    | **Best practice**
-    | Change the line to use spaces only.
+    **Best practice**
+
+    Change the line to use spaces only.
 
     .. code-block:: sql
        :force:

src/sqlfluff/rules/L005.py

@@ -12,9 +12,10 @@ class Rule_L005(BaseRule):
     Unless it's an indent. Trailing/leading commas are dealt with
     in a different rule.
 
-    | **Anti-pattern**
-    | The • character represents a space.
-    | There is an extra space in line two before the comma.
+    **Anti-pattern**
+
+    The ``•`` character represents a space.
+    There is an extra space in line two before the comma.
 
     .. code-block:: sql
        :force:
@@ -24,8 +25,9 @@ class Rule_L005(BaseRule):
             b
         FROM foo
 
-    | **Best practice**
-    | Remove the space before the comma.
+    **Best practice**
+
+    Remove the space before the comma.
 
     .. code-block:: sql
 

src/sqlfluff/rules/L006.py

@@ -19,8 +19,9 @@
 class Rule_L006(BaseRule):
     """Operators should be surrounded by a single whitespace.
 
-    | **Anti-pattern**
-    | In this example, there is a space missing space between the operator and 'b'.
+    **Anti-pattern**
+
+    In this example, there is a space missing between the operator and ``b``.
 
     .. code-block:: sql
 
@@ -29,8 +30,9 @@ class Rule_L006(BaseRule):
         FROM foo
 
 
-    | **Best practice**
-    | Keep a single space.
+    **Best practice**
+
+    Keep a single space.
 
     .. code-block:: sql
 

src/sqlfluff/rules/L007.py

@@ -1,17 +1,19 @@
 """Implementation of Rule L007."""
 from sqlfluff.core.rules.base import BaseRule, LintResult, RuleContext
+from sqlfluff.core.rules.doc_decorators import document_configuration
 
 after_description = "Operators near newlines should be after, not before the newline"
 before_description = "Operators near newlines should be before, not after the newline"
 
 
+@document_configuration
 class Rule_L007(BaseRule):
     """Operators should follow a standard for being before/after newlines.
 
-    | **Anti-pattern**
-    | The • character represents a space.
-    | If ``operator_new_lines = after`` (or unspecified, as this is the default)
-    | In this example, the operator '+' should not be at the end of the second line.
+    **Anti-pattern**
+
+    In this example, if ``operator_new_lines = after`` (or unspecified, as is the
+    default), then the operator ``+`` should not be at the end of the second line.
 
     .. code-block:: sql
 
@@ -21,9 +23,10 @@ class Rule_L007(BaseRule):
         FROM foo
 
 
-    | **Best practice**
-    | If ``operator_new_lines = after`` (or unspecified, as this is the default)
-    | Place the operator after the newline.
+    **Best practice**
+
+    If ``operator_new_lines = after`` (or unspecified, as this is the default),
+    place the operator after the newline.
 
     .. code-block:: sql
 
@@ -32,8 +35,7 @@ class Rule_L007(BaseRule):
             + b
         FROM foo
 
-    | If ``operator_new_lines = before``
-    | Place the operator before the newline.
+    If ``operator_new_lines = before``, place the operator before the newline.
 
     .. code-block:: sql
 

src/sqlfluff/rules/L008.py

@@ -14,9 +14,9 @@
 class Rule_L008(BaseRule):
     """Commas should be followed by a single whitespace unless followed by a comment.
 
-    | **Anti-pattern**
-    | The • character represents a space.
-    | In this example, there is no space between the comma and 'zoo'.
+    **Anti-pattern**
+
+    In this example, there is no space between the comma and ``'zoo'``.
 
     .. code-block:: sql
 
@@ -25,8 +25,9 @@ class Rule_L008(BaseRule):
         FROM foo
         WHERE a IN ('plop','zoo')
 
-    | **Best practice**
-    | Keep a single space after the comma.
+    **Best practice**
+
+    Keep a single space after the comma. The ``•`` character represents a space.
 
     .. code-block:: sql
        :force: