Repository: sqlfluff/sqlfluff
Pull request: Rules documentation improvements
<!--Thanks for adding this feature!-->

<!--Please give the Pull Request a meaningful title for the release notes-->

### Brief summary of the change made
<!--Please include `fixes #XXXX` to automatically close any corresponding issue when the pull request is merged. Alternatively if not fully closed you can say `makes progress on #XXXX`.-->
Fixes #2544 
Fixes #812
as well as making a host of other changes.

I noticed a couple of things that bugged me with the rules documentation page, and ended up going down the rabbit hole and fixing loads of things. None of them are major, but they bug me!

I have also added a new test to check the `@document_configuration` decorator is added when there are config options because it was missing in a lot of cases.

Examples of some things I have fixed in this:

Rule L001:

![image](https://user-images.githubusercontent.com/10931297/152159115-ab24506a-13d8-4bef-b2ea-a62c14a3ca84.png)

Issues:
- The `•` is not code formatted.
- The "`sqlfluff fix` compatible" line looks a bit odd starting with code

New version:

![image](https://user-images.githubusercontent.com/10931297/152159713-39ebe4e9-db60-4d01-bb6c-bf60a952c61d.png)


Rule L004

![image](https://user-images.githubusercontent.com/10931297/152159425-be1ebf8a-e905-4842-87ea-977ae31de0b6.png)

Issues:
- Configuration options are in in italics, instead of code formating.
- Difficult to see how many options (bullet points would be better).
- Large space after Configuration section
- Note is not in note block

New version:

![image](https://user-images.githubusercontent.com/10931297/152159642-5a763f2e-8457-4c0b-9f02-699f7f00da54.png)

Rule L007

![image](https://user-images.githubusercontent.com/10931297/152160247-0e534e55-31aa-4ba3-9b44-9c2081854b04.png)

Issues:
- Config options missing
- Line breaks in Anti-Pattern/Best Practice description

New version:

![image](https://user-images.githubusercontent.com/10931297/152160177-9c36d8f7-8bb4-4501-acde-3d0387b0579f.png)

Rule L009:

![image](https://user-images.githubusercontent.com/10931297/152160320-6c4b43bb-7bae-466a-bb77-f38c8946ed4b.png)

Issues - scrolling in code block

New version:

![image](https://user-images.githubusercontent.com/10931297/152160401-6d38c905-34a3-4302-93e1-918bed1a2be7.png)

### Are there any other side effects of this change that we should be aware of?

Nope, but lots of changes here!

### Pull Request checklist
- [x] Please confirm you have completed any of the necessary steps below.

- Included test cases to demonstrate any code changes, which may be one or more of the following:
  - `.yml` rule test cases in `test/fixtures/rules/std_rule_cases`.
  - `.sql`/`.yml` parser test cases in `test/fixtures/dialects` (note YML files can be auto generated with `tox -e generate-fixture-yml`).
  - Full autofix test cases in `test/fixtures/linter/autofix`.
  - Other.
- Added appropriate documentation for the change.
- Created GitHub issues for any relevant followup/future enhancements if appropriate.


Problem statement:
Rules whose docs need rationales (or improvements to existing ones)
A few rules seem to lack a clear rationale or explanation why they are part of SQLFluff or why SQLFluff considers them "recommended practices". It's important to be clear, because if someone finds a rule annoying, they may want to just disable it. That's fine if they understand the pros and cons of the rule. SQLFluff owes them a description of the pros; if it's unclear, they shouldn't have to go and research the practice on their own. (They are free to do so, but we're building credibility and helping our users _if they don't have to_.)
- L031: The docs don't provide a rationale why this is a best practice. They mention accidental self joins, but a self join may be deliberate. If we added a config option instead to *always* use aliases in join conditions, would that serve the same purpose while also making the code shorter?
- L032: I believe during development of this rule, there was a clear rationale involving corner cases with incorrect behavior. Let's dig this up and add it to the docs. Also, was it specific to certain databases or applicable to all?
- L020, L029: These seem like they detect things that will literally just *fail", don't they? If so, does it make sense for a linter to check for them? Let's explain why" in their docs.


`Rule_L036` does not move lone wildcard to `SELECT` line
> Select targets should be on a new line unless there is only one select target.

It is debatable whether the wildcard is "one select target" or not: looks like one, but potentially contains many).
I expected SQLFluff would not distinguish lone variable from lone *

```
SELECT
    *,
FROM {{ ref('example') }}
```
 
## Expected Behaviour
```
SELECT *,
FROM {{ ref('example') }}
```
 
## Observed Behaviour
```
SELECT
    *,
FROM {{ ref('example') }}
```
 

## Steps to Reproduce

## Dialect
- Standard SQL (seems not important for the case)
- jinja templater

## Version
- sqlfluff==9.1
- Python==3.8.9

## Configuration
- both jinja and dbt templaters do not follow the rule
- L036 is not excluded
- forced trailing coma, but that seems irrelevant even after the last variable

Hints from issue discussion:

Commit message: Remove unnecessary comment

Patch to review:
diff --git a/docs/source/rules.rst b/docs/source/rules.rst
index 7cfd3f71d62..29b050c891f 100644
--- a/docs/source/rules.rst
+++ b/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.
diff --git a/plugins/sqlfluff-plugin-example/src/example/rules.py b/plugins/sqlfluff-plugin-example/src/example/rules.py
index 3730db9bfc8..99b0b26c6d8 100644
--- a/plugins/sqlfluff-plugin-example/src/example/rules.py
+++ b/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
 
diff --git a/src/sqlfluff/core/rules/config_info.py b/src/sqlfluff/core/rules/config_info.py
index dd70b57c734..aa70bb6facb 100644
--- a/src/sqlfluff/core/rules/config_info.py
+++ b/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": {
@@ -139,7 +139,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."
         ),
     },
diff --git a/src/sqlfluff/core/rules/doc_decorators.py b/src/sqlfluff/core/rules/doc_decorators.py
index a70e2013e83..42f4393f1c2 100644
--- a/src/sqlfluff/core/rules/doc_decorators.py
+++ b/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__
diff --git a/src/sqlfluff/rules/L001.py b/src/sqlfluff/rules/L001.py
index 1275d60d8c2..d0ef355a430 100644
--- a/src/sqlfluff/rules/L001.py
+++ b/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
 
diff --git a/src/sqlfluff/rules/L002.py b/src/sqlfluff/rules/L002.py
index cb9eb3031ce..650807ba6de 100644
--- a/src/sqlfluff/rules/L002.py
+++ b/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:
diff --git a/src/sqlfluff/rules/L003.py b/src/sqlfluff/rules/L003.py
index e107f2e13ea..203f245750d 100644
--- a/src/sqlfluff/rules/L003.py
+++ b/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:
diff --git a/src/sqlfluff/rules/L004.py b/src/sqlfluff/rules/L004.py
index fca731d0d0e..a73e166130c 100644
--- a/src/sqlfluff/rules/L004.py
+++ b/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 spaces (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:
diff --git a/src/sqlfluff/rules/L005.py b/src/sqlfluff/rules/L005.py
index 9219f0e55ed..9bf6169ef6f 100644
--- a/src/sqlfluff/rules/L005.py
+++ b/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
 
diff --git a/src/sqlfluff/rules/L006.py b/src/sqlfluff/rules/L006.py
index 294491c0f6b..5906cf1c4e0 100644
--- a/src/sqlfluff/rules/L006.py
+++ b/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 space 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
 
diff --git a/src/sqlfluff/rules/L007.py b/src/sqlfluff/rules/L007.py
index b4079b12008..223ba866ceb 100644
--- a/src/sqlfluff/rules/L007.py
+++ b/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**
+
+    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.
 
     .. 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
 
diff --git a/src/sqlfluff/rules/L008.py b/src/sqlfluff/rules/L008.py
index c16d246741b..65c834cf819 100644
--- a/src/sqlfluff/rules/L008.py
+++ b/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:
diff --git a/src/sqlfluff/rules/L009.py b/src/sqlfluff/rules/L009.py
index afe98c73af3..b0c83a619a4 100644
--- a/src/sqlfluff/rules/L009.py
+++ b/src/sqlfluff/rules/L009.py
@@ -12,9 +12,10 @@
 class Rule_L009(BaseRule):
     """Files must end with a single trailing newline.
 
-    | **Anti-pattern**
-    | The content in file does not end with a single trailing newline, the $ represents
-    | end of file.
+    **Anti-pattern**
+
+    The content in file does not end with a single trailing newline, the ``$``
+    represents end of file.
 
     .. code-block:: sql
        :force:
@@ -23,8 +24,8 @@ class Rule_L009(BaseRule):
             a
         FROM foo$
 
-        -- Ending on an indented line means there is no newline at the end of the file,
-        -- the • represents space.
+        -- Ending on an indented line means there is no newline
+        -- at the end of the file, the • represents space.
 
         SELECT
         ••••a
@@ -32,7 +33,8 @@ class Rule_L009(BaseRule):
         ••••foo
         ••••$
 
-        -- Ending on a semi-colon means the last line is not a newline.
+        -- Ending on a semi-colon means the last line is not a
+        -- newline.
 
         SELECT
             a
@@ -47,8 +49,9 @@ class Rule_L009(BaseRule):
 
         $
 
-    | **Best practice**
-    | Add trailing newline to the end, the $ character represents end of file.
+    **Best practice**
+
+    Add trailing newline to the end, the ``$`` character represents end of file.
 
     .. code-block:: sql
        :force:
@@ -58,7 +61,8 @@ class Rule_L009(BaseRule):
         FROM foo
         $
 
-        -- Ensuring the last line is not indented so is just a newline.
+        -- Ensuring the last line is not indented so is just a
+        -- newline.
 
         SELECT
         ••••a
@@ -66,7 +70,8 @@ class Rule_L009(BaseRule):
         ••••foo
         $
 
-        -- Even when ending on a semi-colon, ensure there is a newline after
+        -- Even when ending on a semi-colon, ensure there is a
+        -- newline after.
 
         SELECT
             a
diff --git a/src/sqlfluff/rules/L010.py b/src/sqlfluff/rules/L010.py
index ce775a17f7e..93839f537b8 100644
--- a/src/sqlfluff/rules/L010.py
+++ b/src/sqlfluff/rules/L010.py
@@ -15,8 +15,9 @@
 class Rule_L010(BaseRule):
     """Inconsistent capitalisation of keywords.
 
-    | **Anti-pattern**
-    | In this example, 'select 'is in lower-case whereas 'FROM' is in upper-case.
+    **Anti-pattern**
+
+    In this example, ``select`` is in lower-case whereas ``FROM`` is in upper-case.
 
     .. code-block:: sql
 
@@ -24,8 +25,9 @@ class Rule_L010(BaseRule):
             a
         FROM foo
 
-    | **Best practice**
-    | Make all keywords either in upper-case or in lower-case
+    **Best practice**
+
+    Make all keywords either in upper-case or in lower-case
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L011.py b/src/sqlfluff/rules/L011.py
index 491fd97e10f..3a72586071e 100644
--- a/src/sqlfluff/rules/L011.py
+++ b/src/sqlfluff/rules/L011.py
@@ -7,18 +7,23 @@
 )
 
 from sqlfluff.core.rules.base import BaseRule, LintResult, LintFix, RuleContext
-from sqlfluff.core.rules.doc_decorators import document_fix_compatible
+from sqlfluff.core.rules.doc_decorators import (
+    document_fix_compatible,
+    document_configuration,
+)
 
 
 @document_fix_compatible
+@document_configuration
 class Rule_L011(BaseRule):
     """Implicit/explicit aliasing of table.
 
     Aliasing of table to follow preference
-    (explicit using an `AS` clause is default).
+    (explicit using an ``AS`` clause is default).
+
+    **Anti-pattern**
 
-    | **Anti-pattern**
-    | In this example, the alias 'voo' is implicit.
+    In this example, the alias ``voo`` is implicit.
 
     .. code-block:: sql
 
@@ -26,8 +31,9 @@ class Rule_L011(BaseRule):
             voo.a
         FROM foo voo
 
-    | **Best practice**
-    | Add `AS` to make it explicit.
+    **Best practice**
+
+    Add ``AS`` to make it explicit.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L012.py b/src/sqlfluff/rules/L012.py
index a004d454d60..a1e0bb2e335 100644
--- a/src/sqlfluff/rules/L012.py
+++ b/src/sqlfluff/rules/L012.py
@@ -1,19 +1,23 @@
 """Implementation of Rule L012."""
 
 from sqlfluff.rules.L011 import Rule_L011
+from sqlfluff.core.rules.doc_decorators import document_configuration
 
 
+@document_configuration
 class Rule_L012(Rule_L011):
     """Implicit/explicit aliasing of columns.
 
     Aliasing of columns to follow preference
-    (explicit using an `AS` clause is default).
+    (explicit using an ``AS`` clause is default).
 
-    NB: This rule inherits its functionality from :obj:`Rule_L011` but is
-    separate so that they can be enabled and disabled separately.
+    .. note::
+       This rule inherits its functionality from :obj:`Rule_L011` but is
+       separate so that they can be enabled and disabled separately.
 
-    | **Anti-pattern**
-    | In this example, the alias for column 'a' is implicit.
+    **Anti-pattern**
+
+    In this example, the alias for column ``a`` is implicit.
 
     .. code-block:: sql
 
@@ -21,8 +25,9 @@ class Rule_L012(Rule_L011):
             a alias_col
         FROM foo
 
-    | **Best practice**
-    | Add `AS` to make it explicit.
+    **Best practice**
+
+    Add ``AS`` to make it explicit.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L013.py b/src/sqlfluff/rules/L013.py
index d97d7a0f9d9..1e784243a8a 100644
--- a/src/sqlfluff/rules/L013.py
+++ b/src/sqlfluff/rules/L013.py
@@ -10,8 +10,9 @@
 class Rule_L013(BaseRule):
     """Column expression without alias. Use explicit `AS` clause.
 
-    | **Anti-pattern**
-    | In this example, there is no alias for both sums.
+    **Anti-pattern**
+
+    In this example, there is no alias for both sums.
 
     .. code-block:: sql
 
@@ -20,8 +21,9 @@ class Rule_L013(BaseRule):
             sum(b)
         FROM foo
 
-    | **Best practice**
-    | Add aliases.
+    **Best practice**
+
+    Add aliases.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L014.py b/src/sqlfluff/rules/L014.py
index 182ad3bdf3f..874a08c62e3 100644
--- a/src/sqlfluff/rules/L014.py
+++ b/src/sqlfluff/rules/L014.py
@@ -37,9 +37,10 @@ class Rule_L014(Rule_L010):
 
     The functionality for this rule is inherited from :obj:`Rule_L010`.
 
-    | **Anti-pattern**
-    | In this example, unquoted identifier 'a' is in lower-case but
-    | 'B' is in upper-case.
+    **Anti-pattern**
+
+    In this example, unquoted identifier ``a`` is in lower-case but
+    ``B`` is in upper-case.
 
     .. code-block:: sql
 
@@ -48,8 +49,9 @@ class Rule_L014(Rule_L010):
             B
         from foo
 
-    | **Best practice**
-    | Ensure all unquoted identifiers are either in upper-case or in lower-case
+    **Best practice**
+
+    Ensure all unquoted identifiers are either in upper-case or in lower-case
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L015.py b/src/sqlfluff/rules/L015.py
index c74cb3a5a87..ede8ae1da4d 100644
--- a/src/sqlfluff/rules/L015.py
+++ b/src/sqlfluff/rules/L015.py
@@ -12,18 +12,20 @@
 class Rule_L015(BaseRule):
     """``DISTINCT`` used with parentheses.
 
-    | **Anti-pattern**
-    | In this example, parenthesis are not needed and confuse
-    | ``DISTINCT`` with a function. The parenthesis can also be misleading
-    | in which columns they apply to.
+    **Anti-pattern**
+
+    In this example, parenthesis are not needed and confuse
+    ``DISTINCT`` with a function. The parenthesis can also be misleading
+    in which columns they apply to.
 
     .. code-block:: sql
 
         SELECT DISTINCT(a), b FROM foo
 
-    | **Best practice**
-    | Remove parenthesis to be clear that the ``DISTINCT`` applies to
-    | both columns.
+    **Best practice**
+
+    Remove parenthesis to be clear that the ``DISTINCT`` applies to
+    both columns.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L017.py b/src/sqlfluff/rules/L017.py
index 3d67735c5bd..8b209164628 100644
--- a/src/sqlfluff/rules/L017.py
+++ b/src/sqlfluff/rules/L017.py
@@ -9,8 +9,9 @@
 class Rule_L017(BaseRule):
     """Function name not immediately followed by bracket.
 
-    | **Anti-pattern**
-    | In this example, there is a space between the function and the parenthesis.
+    **Anti-pattern**
+
+    In this example, there is a space between the function and the parenthesis.
 
     .. code-block:: sql
 
@@ -18,8 +19,9 @@ class Rule_L017(BaseRule):
             sum (a)
         FROM foo
 
-    | **Best practice**
-    | Remove the space between the function and the parenthesis.
+    **Best practice**
+
+    Remove the space between the function and the parenthesis.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L018.py b/src/sqlfluff/rules/L018.py
index d8109bfc9ba..f8d3551da5b 100644
--- a/src/sqlfluff/rules/L018.py
+++ b/src/sqlfluff/rules/L018.py
@@ -3,16 +3,21 @@
 from sqlfluff.core.parser import NewlineSegment, WhitespaceSegment
 
 from sqlfluff.core.rules.base import BaseRule, LintFix, LintResult, RuleContext
-from sqlfluff.core.rules.doc_decorators import document_fix_compatible
+from sqlfluff.core.rules.doc_decorators import (
+    document_fix_compatible,
+    document_configuration,
+)
 
 
 @document_fix_compatible
+@document_configuration
 class Rule_L018(BaseRule):
     """``WITH`` clause closing bracket should be aligned with ``WITH`` keyword.
 
-    | **Anti-pattern**
-    | The • character represents a space.
-    | In this example, the closing bracket is not aligned with ``WITH`` keyword.
+    **Anti-pattern**
+
+    The ``•`` character represents a space.
+    In this example, the closing bracket is not aligned with ``WITH`` keyword.
 
     .. code-block:: sql
        :force:
@@ -23,8 +28,9 @@ class Rule_L018(BaseRule):
 
         SELECT * FROM zoo
 
-    | **Best practice**
-    | Remove the spaces to align the ``WITH`` keyword with the closing bracket.
+    **Best practice**
+
+    Remove the spaces to align the ``WITH`` keyword with the closing bracket.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L019.py b/src/sqlfluff/rules/L019.py
index 8aa598c1cac..e700f26d015 100644
--- a/src/sqlfluff/rules/L019.py
+++ b/src/sqlfluff/rules/L019.py
@@ -15,8 +15,9 @@
 class Rule_L019(BaseRule):
     """Leading/Trailing comma enforcement.
 
-    | **Anti-pattern**
-    | There is a mixture of leading and trailing commas.
+    **Anti-pattern**
+
+    There is a mixture of leading and trailing commas.
 
     .. code-block:: sql
 
@@ -26,10 +27,11 @@ class Rule_L019(BaseRule):
             c
         FROM foo
 
-    | **Best practice**
-    | By default sqlfluff prefers trailing commas, however it
-    | is configurable for leading commas. Whichever option you chose
-    | it does expect you to be consistent.
+    **Best practice**
+
+    By default sqlfluff prefers trailing commas, however it
+    is configurable for leading commas. Whichever option you chose
+    it does expect you to be consistent.
 
     .. code-block:: sql
 
@@ -47,8 +49,6 @@ class Rule_L019(BaseRule):
             , b
             , c
         FROM foo
-
-
     """
 
     _works_on_unparsable = False
diff --git a/src/sqlfluff/rules/L020.py b/src/sqlfluff/rules/L020.py
index a3849ea64d0..f6a569a76e3 100644
--- a/src/sqlfluff/rules/L020.py
+++ b/src/sqlfluff/rules/L020.py
@@ -12,8 +12,9 @@
 class Rule_L020(BaseRule):
     """Table aliases should be unique within each clause.
 
-    | **Anti-pattern**
-    | In this example, the alias 't' is reused for two different tables:
+    **Anti-pattern**
+
+    In this example, the alias ``t`` is reused for two different tables:
 
     .. code-block:: sql
 
@@ -22,8 +23,8 @@ class Rule_L020(BaseRule):
             t.b
         FROM foo AS t, bar AS t
 
-        -- this can also happen when using schemas where the implicit alias is the table
-        -- name:
+        -- This can also happen when using schemas where the
+        -- implicit alias is the table name:
 
         SELECT
             a,
@@ -32,8 +33,9 @@ class Rule_L020(BaseRule):
             2020.foo,
             2021.foo
 
-    | **Best practice**
-    | Make all tables have a unique alias
+    **Best practice**
+
+    Make all tables have a unique alias
 
     .. code-block:: sql
 
@@ -42,8 +44,8 @@ class Rule_L020(BaseRule):
             b.b
         FROM foo AS f, bar AS b
 
-        -- Also use explicit alias's when referencing two tables with same name from two
-        -- different schemas
+        -- Also use explicit alias's when referencing two tables
+        -- with same name from two different schemas
 
         SELECT
             f1.a,
diff --git a/src/sqlfluff/rules/L021.py b/src/sqlfluff/rules/L021.py
index 9cf45c76d24..c6229e65b4a 100644
--- a/src/sqlfluff/rules/L021.py
+++ b/src/sqlfluff/rules/L021.py
@@ -8,8 +8,9 @@
 class Rule_L021(BaseRule):
     """Ambiguous use of ``DISTINCT`` in select statement with ``GROUP BY``.
 
-    | **Anti-pattern**
-    | ``DISTINCT`` and ``GROUP BY`` are conflicting.
+    **Anti-pattern**
+
+    ``DISTINCT`` and ``GROUP BY`` are conflicting.
 
     .. code-block:: sql
 
@@ -18,8 +19,9 @@ class Rule_L021(BaseRule):
         FROM foo
         GROUP BY a
 
-    | **Best practice**
-    | Remove ``DISTINCT`` or ``GROUP BY``. In our case, removing GROUP BY is better.
+    **Best practice**
+
+    Remove ``DISTINCT`` or ``GROUP BY``. In our case, removing ``GROUP BY`` is better.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L022.py b/src/sqlfluff/rules/L022.py
index 3f9624342a5..a599de6e3ba 100644
--- a/src/sqlfluff/rules/L022.py
+++ b/src/sqlfluff/rules/L022.py
@@ -4,16 +4,21 @@
 from sqlfluff.core.parser import NewlineSegment
 
 from sqlfluff.core.rules.base import BaseRule, LintFix, LintResult, RuleContext
-from sqlfluff.core.rules.doc_decorators import document_fix_compatible
+from sqlfluff.core.rules.doc_decorators import (
+    document_fix_compatible,
+    document_configuration,
+)
 
 
 @document_fix_compatible
+@document_configuration
 class Rule_L022(BaseRule):
     """Blank line expected but not found after CTE closing bracket.
 
-    | **Anti-pattern**
-    | There is no blank line after the CTE closing bracket. In queries with many
-    | CTEs this hinders readability.
+    **Anti-pattern**
+
+    There is no blank line after the CTE closing bracket. In queries with many
+    CTEs this hinders readability.
 
     .. code-block:: sql
 
@@ -22,8 +27,9 @@ class Rule_L022(BaseRule):
         )
         SELECT a FROM plop
 
-    | **Best practice**
-    | Add a blank line.
+    **Best practice**
+
+    Add a blank line.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L023.py b/src/sqlfluff/rules/L023.py
index 18b103bb03c..8e1af306a2e 100644
--- a/src/sqlfluff/rules/L023.py
+++ b/src/sqlfluff/rules/L023.py
@@ -12,7 +12,7 @@
 class Rule_L023(BaseRule):
     """Single whitespace expected after ``AS`` in ``WITH`` clause.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -23,10 +23,10 @@ class Rule_L023(BaseRule):
         SELECT a FROM plop
 
 
-    | **Best practice**
-    | The • character represents a space.
-    | Add a space after ``AS``, to avoid confusing
-    | it for a function.
+    **Best practice**
+
+    Add a space after ``AS``, to avoid confusing it for a function.
+    The ``•`` character represents a space.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L024.py b/src/sqlfluff/rules/L024.py
index 7b96f006c81..7df092b2be0 100644
--- a/src/sqlfluff/rules/L024.py
+++ b/src/sqlfluff/rules/L024.py
@@ -9,7 +9,7 @@
 class Rule_L024(Rule_L023):
     """Single whitespace expected after ``USING`` in ``JOIN`` clause.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -17,18 +17,17 @@ class Rule_L024(Rule_L023):
         FROM foo
         LEFT JOIN zoo USING(a)
 
-    | **Best practice**
-    | The • character represents a space.
-    | Add a space after ``USING``, to avoid confusing it
-    | for a function.
+    **Best practice**
+
+    Add a space after ``USING``, to avoid confusing it
+    for a function.
 
     .. code-block:: sql
        :force:
 
         SELECT b
         FROM foo
-        LEFT JOIN zoo USING•(a)
-
+        LEFT JOIN zoo USING (a)
     """
 
     expected_mother_segment_type = "join_clause"
diff --git a/src/sqlfluff/rules/L025.py b/src/sqlfluff/rules/L025.py
index 5b9d0a83265..c720878769f 100644
--- a/src/sqlfluff/rules/L025.py
+++ b/src/sqlfluff/rules/L025.py
@@ -33,7 +33,7 @@ class L025Query(SelectCrawlerQuery):
 class Rule_L025(BaseRule):
     """Tables should not be aliased if that alias is not used.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -41,9 +41,10 @@ class Rule_L025(BaseRule):
             a
         FROM foo AS zoo
 
-    | **Best practice**
-    | Use the alias or remove it. An unused alias makes code
-    | harder to read without changing any functionality.
+    **Best practice**
+
+    Use the alias or remove it. An unused alias makes code
+    harder to read without changing any functionality.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L026.py b/src/sqlfluff/rules/L026.py
index 4b007a3f0ce..f0c2061a59e 100644
--- a/src/sqlfluff/rules/L026.py
+++ b/src/sqlfluff/rules/L026.py
@@ -30,12 +30,14 @@ class L026Query(SelectCrawlerQuery):
 class Rule_L026(BaseRule):
     """References cannot reference objects not present in ``FROM`` clause.
 
-    NB: This rule is disabled by default for BigQuery due to its use of
-    structs which trigger false positives. It can be enabled with the
-    ``force_enable = True`` flag.
+    .. note::
+       This rule is disabled by default for BigQuery due to its use of
+       structs which trigger false positives. It can be enabled with the
+       ``force_enable = True`` flag.
 
-    | **Anti-pattern**
-    | In this example, the reference ``vee`` has not been declared.
+    **Anti-pattern**
+
+    In this example, the reference ``vee`` has not been declared.
 
     .. code-block:: sql
 
@@ -43,8 +45,9 @@ class Rule_L026(BaseRule):
             vee.a
         FROM foo
 
-    | **Best practice**
-    |  Remove the reference.
+    **Best practice**
+
+    Remove the reference.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L027.py b/src/sqlfluff/rules/L027.py
index cfee82caf41..bd5b044dda4 100644
--- a/src/sqlfluff/rules/L027.py
+++ b/src/sqlfluff/rules/L027.py
@@ -7,11 +7,13 @@
 class Rule_L027(Rule_L020):
     """References should be qualified if select has more than one referenced table/view.
 
-    NB: Except if they're present in a ``USING`` clause.
+    .. note::
+       Except if they're present in a ``USING`` clause.
 
-    | **Anti-pattern**
-    | In this example, the reference ``vee`` has not been declared
-    | and the variables ``a`` and ``b`` are potentially ambiguous.
+    **Anti-pattern**
+
+    In this example, the reference ``vee`` has not been declared
+    and the variables ``a`` and ``b`` are potentially ambiguous.
 
     .. code-block:: sql
 
@@ -19,8 +21,9 @@ class Rule_L027(Rule_L020):
         FROM foo
         LEFT JOIN vee ON vee.a = foo.a
 
-    | **Best practice**
-    |  Add the references.
+    **Best practice**
+
+    Add the references.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L028.py b/src/sqlfluff/rules/L028.py
index 978181b54df..e5f49f3205b 100644
--- a/src/sqlfluff/rules/L028.py
+++ b/src/sqlfluff/rules/L028.py
@@ -9,12 +9,14 @@
 class Rule_L028(Rule_L020):
     """References should be consistent in statements with a single table.
 
-    NB: This rule is disabled by default for BigQuery due to its use of
-    structs which trigger false positives. It can be enabled with the
-    ``force_enable = True`` flag.
+    .. note::
+       This rule is disabled by default for BigQuery due to its use of
+       structs which trigger false positives. It can be enabled with the
+       ``force_enable = True`` flag.
 
-    | **Anti-pattern**
-    | In this example, only the field ``b`` is referenced.
+    **Anti-pattern**
+
+    In this example, only the field ``b`` is referenced.
 
     .. code-block:: sql
 
@@ -23,8 +25,9 @@ class Rule_L028(Rule_L020):
             foo.b
         FROM foo
 
-    | **Best practice**
-    |  Add or remove references to all fields.
+    **Best practice**
+
+    Add or remove references to all fields.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L029.py b/src/sqlfluff/rules/L029.py
index f2e2932bfdd..f998529faea 100644
--- a/src/sqlfluff/rules/L029.py
+++ b/src/sqlfluff/rules/L029.py
@@ -10,8 +10,9 @@
 class Rule_L029(BaseRule):
     """Keywords should not be used as identifiers.
 
-    | **Anti-pattern**
-    | In this example, ``SUM`` (built-in function) is used as an alias.
+    **Anti-pattern**
+
+    In this example, ``SUM`` (built-in function) is used as an alias.
 
     .. code-block:: sql
 
@@ -19,8 +20,9 @@ class Rule_L029(BaseRule):
             sum.a
         FROM foo AS sum
 
-    | **Best practice**
-    |  Avoid keywords as the name of an alias.
+    **Best practice**
+
+    Avoid keywords as the name of an alias.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L030.py b/src/sqlfluff/rules/L030.py
index 074b41b7eee..8ea5c37ff20 100644
--- a/src/sqlfluff/rules/L030.py
+++ b/src/sqlfluff/rules/L030.py
@@ -16,8 +16,9 @@ class Rule_L030(Rule_L010):
 
     The functionality for this rule is inherited from :obj:`Rule_L010`.
 
-    | **Anti-pattern**
-    | In this example, the two ``SUM`` functions don't have the same capitalisation.
+    **Anti-pattern**
+
+    In this example, the two ``SUM`` functions don't have the same capitalisation.
 
     .. code-block:: sql
 
@@ -26,8 +27,9 @@ class Rule_L030(Rule_L010):
             SUM(b) AS bb
         FROM foo
 
-    | **Best practice**
-    |  Make the case consistent.
+    **Best practice**
+
+    Make the case consistent.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L031.py b/src/sqlfluff/rules/L031.py
index ba081505b3e..ba931830f7e 100644
--- a/src/sqlfluff/rules/L031.py
+++ b/src/sqlfluff/rules/L031.py
@@ -22,9 +22,10 @@ class TableAliasInfo(NamedTuple):
 class Rule_L031(BaseRule):
     """Avoid table aliases in from clauses and join conditions.
 
-    | **Anti-pattern**
-    | In this example, alias ``o`` is used for the orders table, and ``c`` is used for
-    | 'customers' table.
+    **Anti-pattern**
+
+    In this example, alias ``o`` is used for the orders table, and ``c`` is used for
+    ``customers`` table.
 
     .. code-block:: sql
 
@@ -35,8 +36,9 @@ class Rule_L031(BaseRule):
         JOIN customers as c on o.id = c.user_id
 
 
-    | **Best practice**
-    |  Avoid aliases.
+    **Best practice**
+
+    Avoid aliases.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L032.py b/src/sqlfluff/rules/L032.py
index ce8477deb5c..8a210bd5bc3 100644
--- a/src/sqlfluff/rules/L032.py
+++ b/src/sqlfluff/rules/L032.py
@@ -7,7 +7,7 @@
 class Rule_L032(BaseRule):
     """Prefer specifying join keys instead of using ``USING``.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -18,8 +18,9 @@ class Rule_L032(BaseRule):
             table_a
         INNER JOIN table_b USING (id)
 
-    | **Best practice**
-    |  Specify the keys directly
+    **Best practice**
+
+    Specify the keys directly
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L033.py b/src/sqlfluff/rules/L033.py
index 941ab8eeb1a..9d4a8df8d52 100644
--- a/src/sqlfluff/rules/L033.py
+++ b/src/sqlfluff/rules/L033.py
@@ -10,24 +10,31 @@
 class Rule_L033(BaseRule):
     """``UNION [DISTINCT|ALL]`` is preferred over just ``UNION``.
 
-    NB: This rule is only enabled for dialects that support ``UNION DISTINCT``
-    (``ansi``, ``bigquery``, ``hive``, and ``mysql``).
+    .. note::
+       This rule is only enabled for dialects that support ``UNION DISTINCT``
+       (``ansi``, ``bigquery``, ``hive``, and ``mysql``).
 
-    | **Anti-pattern**
-    | In this example, ``UNION DISTINCT`` should be preferred over ``UNION``, because
-    | explicit is better than implicit.
+    **Anti-pattern**
+
+    In this example, ``UNION DISTINCT`` should be preferred over ``UNION``, because
+    explicit is better than implicit.
 
     .. code-block:: sql
 
-        SELECT a, b FROM table_1 UNION SELECT a, b FROM table_2
+        SELECT a, b FROM table_1
+        UNION
+        SELECT a, b FROM table_2
+
+    **Best practice**
 
-    | **Best practice**
-    | Specify ``DISTINCT`` or ``ALL`` after ``UNION``. (Note that ``DISTINCT`` is the
-    | default behavior.
+    Specify ``DISTINCT`` or ``ALL`` after ``UNION`` (note that ``DISTINCT`` is the
+    default behavior).
 
     .. code-block:: sql
 
-        SELECT a, b FROM table_1 UNION DISTINCT SELECT a, b FROM table_2
+        SELECT a, b FROM table_1
+        UNION DISTINCT
+        SELECT a, b FROM table_2
 
     """
 
diff --git a/src/sqlfluff/rules/L034.py b/src/sqlfluff/rules/L034.py
index 3958a84856d..9df98fecf5b 100644
--- a/src/sqlfluff/rules/L034.py
+++ b/src/sqlfluff/rules/L034.py
@@ -10,7 +10,7 @@
 class Rule_L034(BaseRule):
     """Select wildcards then simple targets before calculations and aggregates.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -22,8 +22,9 @@ class Rule_L034(BaseRule):
         from x
 
 
-    | **Best practice**
-    |  Order "select" targets in ascending complexity
+    **Best practice**
+
+    Order ``select`` targets in ascending complexity
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L035.py b/src/sqlfluff/rules/L035.py
index 9bbbbbd9e82..e17f4d4685a 100644
--- a/src/sqlfluff/rules/L035.py
+++ b/src/sqlfluff/rules/L035.py
@@ -10,7 +10,7 @@
 class Rule_L035(BaseRule):
     """Do not specify ``else null`` in a case when statement (redundant).
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -22,8 +22,9 @@ class Rule_L035(BaseRule):
             end
         from x
 
-    | **Best practice**
-    |  Omit ``else null``
+    **Best practice**
+
+    Omit ``else null``
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L036.py b/src/sqlfluff/rules/L036.py
index 93d59c6b39d..f7d8d5c7f91 100644
--- a/src/sqlfluff/rules/L036.py
+++ b/src/sqlfluff/rules/L036.py
@@ -27,8 +27,9 @@ class SelectTargetsInfo(NamedTuple):
 class Rule_L036(BaseRule):
     """Select targets should be on a new line unless there is only one select target.
 
-    | **Anti-pattern**
-    | Multiple select targets on the same line.
+    **Anti-pattern**
+
+    Multiple select targets on the same line.
 
     .. code-block:: sql
         :force:
@@ -43,8 +44,9 @@ class Rule_L036(BaseRule):
         FROM foo
 
 
-    | **Best practice**
-    | Multiple select targets each on their own line.
+    **Best practice**
+
+    Multiple select targets each on their own line.
 
     .. code-block:: sql
         :force:
@@ -54,7 +56,8 @@ class Rule_L036(BaseRule):
             b
         from foo
 
-        -- Single select target on the same line as the SELECT keyword.
+        -- Single select target on the same line as the SELECT
+        -- keyword.
 
         SELECT a
         FROM foo
diff --git a/src/sqlfluff/rules/L037.py b/src/sqlfluff/rules/L037.py
index cc654d4166d..6e7b367cedc 100644
--- a/src/sqlfluff/rules/L037.py
+++ b/src/sqlfluff/rules/L037.py
@@ -20,7 +20,7 @@ class OrderByColumnInfo(NamedTuple):
 class Rule_L037(BaseRule):
     """Ambiguous ordering directions for columns in order by clause.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -29,9 +29,10 @@ class Rule_L037(BaseRule):
         FROM foo
         ORDER BY a, b DESC
 
-    | **Best practice**
-    | If any columns in the ORDER BY clause specify ASC or DESC, they should all
-      do so.
+    **Best practice**
+
+    If any columns in the ``ORDER BY`` clause specify ``ASC`` or ``DESC``, they should
+    all do so.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L038.py b/src/sqlfluff/rules/L038.py
index 9d4ad881c31..479ca7badbb 100644
--- a/src/sqlfluff/rules/L038.py
+++ b/src/sqlfluff/rules/L038.py
@@ -16,26 +16,29 @@
 class Rule_L038(BaseRule):
     """Trailing commas within select clause.
 
-    For some database backends this is allowed. For some users
-    this may be something they wish to enforce (in line with
-    python best practice). Many database backends regard this
-    as a syntax error, and as such the sqlfluff default is to
-    forbid trailing commas in the select clause.
+    .. note::
+       For many database backends this is allowed. For some users
+       this may be something they wish to enforce (in line with
+       python best practice). Many database backends regard this
+       as a syntax error, and as such the SQLFluff default is to
+       forbid trailing commas in the select clause.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
         SELECT
-            a, b,
+            a,
+            b,
         FROM foo
 
-    | **Best practice**
+    **Best practice**
 
     .. code-block:: sql
 
         SELECT
-            a, b
+            a,
+            b
         FROM foo
     """
 
diff --git a/src/sqlfluff/rules/L039.py b/src/sqlfluff/rules/L039.py
index a240fc3b57c..399e225a298 100644
--- a/src/sqlfluff/rules/L039.py
+++ b/src/sqlfluff/rules/L039.py
@@ -12,7 +12,7 @@
 class Rule_L039(BaseRule):
     """Unnecessary whitespace found.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -20,9 +20,10 @@ class Rule_L039(BaseRule):
             a,        b
         FROM foo
 
-    | **Best practice**
-    | Unless an indent or preceding a comment, whitespace should
-    | be a single space.
+    **Best practice**
+
+    Unless an indent or preceding a comment, whitespace should
+    be a single space.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L040.py b/src/sqlfluff/rules/L040.py
index b1c828cfedd..bd6c1dd82ba 100644
--- a/src/sqlfluff/rules/L040.py
+++ b/src/sqlfluff/rules/L040.py
@@ -16,9 +16,10 @@ class Rule_L040(Rule_L010):
 
     The functionality for this rule is inherited from :obj:`Rule_L010`.
 
-    | **Anti-pattern**
-    | In this example, 'null' and 'false' are in lower-case whereas 'TRUE' is in
-    | upper-case.
+    **Anti-pattern**
+
+    In this example, ``null`` and ``false`` are in lower-case whereas ``TRUE`` is in
+    upper-case.
 
     .. code-block:: sql
 
@@ -29,8 +30,9 @@ class Rule_L040(Rule_L010):
             false
         from foo
 
-    | **Best practice**
-    | Ensure all literal null/true/false literals cases are used consistently
+    **Best practice**
+
+    Ensure all literal ``null``/``true``/``false`` literals cases are used consistently
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L041.py b/src/sqlfluff/rules/L041.py
index 1196a738bf8..5d3c983823a 100644
--- a/src/sqlfluff/rules/L041.py
+++ b/src/sqlfluff/rules/L041.py
@@ -12,7 +12,7 @@
 class Rule_L041(BaseRule):
     """``SELECT`` modifiers (e.g. ``DISTINCT``) must be on the same line as ``SELECT``.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -22,7 +22,7 @@ class Rule_L041(BaseRule):
         from x
 
 
-    | **Best practice**
+    **Best practice**
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L042.py b/src/sqlfluff/rules/L042.py
index 3db3955781a..47b83edcf68 100644
--- a/src/sqlfluff/rules/L042.py
+++ b/src/sqlfluff/rules/L042.py
@@ -14,10 +14,11 @@ class Rule_L042(BaseRule):
     clauses but not within ``JOIN`` clauses. If you prefer a stricter lint
     then this is configurable.
 
-    NB: Some dialects don't allow CTEs, and for those dialects
-    this rule makes no sense and should be disabled.
+    .. note::
+       Some dialects don't allow CTEs, and for those dialects
+       this rule makes no sense and should be disabled.
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -29,7 +30,7 @@ class Rule_L042(BaseRule):
         ) using(x)
 
 
-    | **Best practice**
+    **Best practice**
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L043.py b/src/sqlfluff/rules/L043.py
index 13cf2a96fc4..389e150e1ab 100644
--- a/src/sqlfluff/rules/L043.py
+++ b/src/sqlfluff/rules/L043.py
@@ -17,8 +17,9 @@
 class Rule_L043(BaseRule):
     """Unnecessary ``CASE`` statement.
 
-    | **Anti-pattern**
-    | ``CASE`` statement returns booleans.
+    **Anti-pattern**
+
+    ``CASE`` statement returns booleans.
 
     .. code-block:: sql
         :force:
@@ -50,8 +51,9 @@ class Rule_L043(BaseRule):
             end as fab_clean
         from fancy_table
 
-    | **Best practice**
-    | Reduce to ``WHEN`` condition within ``COALESCE`` function.
+    **Best practice**
+
+    Reduce to ``WHEN`` condition within ``COALESCE`` function.
 
     .. code-block:: sql
         :force:
diff --git a/src/sqlfluff/rules/L044.py b/src/sqlfluff/rules/L044.py
index 779cc67805d..ac6e18ad2f8 100644
--- a/src/sqlfluff/rules/L044.py
+++ b/src/sqlfluff/rules/L044.py
@@ -17,22 +17,23 @@ def __init__(self, anchor: BaseSegment):
 class Rule_L044(BaseRule):
     """Query produces an unknown number of result columns.
 
-    | **Anti-pattern**
-    | Querying all columns using `*` produces a query result where the number
-    | or ordering of columns changes if the upstream table's schema changes.
-    | This should generally be avoided because it can cause slow performance,
-    | cause important schema changes to go undetected, or break production code.
-    | For example:
-    |
-    | * If a query does `SELECT t.*` and is expected to return columns `a`, `b`,
-    |   and `c`, the actual columns returned will be wrong/different if columns
-    |   are added to or deleted from the input table.
-    | * `UNION` and `DIFFERENCE` clauses require the inputs have the same number
-    |   of columns (and compatible types).
-    | * `JOIN` queries may break due to new column name conflicts, e.g. the
-    |   query references a column "c" which initially existed in only one input
-    |   table but a column of the same name is added to another table.
-    | * `CREATE TABLE (<<column schema>>) AS SELECT *`
+    **Anti-pattern**
+
+    Querying all columns using ``*`` produces a query result where the number
+    or ordering of columns changes if the upstream table's schema changes.
+    This should generally be avoided because it can cause slow performance,
+    cause important schema changes to go undetected, or break production code.
+    For example:
+
+    * If a query does ``SELECT t.*`` and is expected to return columns ``a``, ``b``,
+      and ``c``, the actual columns returned will be wrong/different if columns
+      are added to or deleted from the input table.
+    * ``UNION`` and ``DIFFERENCE`` clauses require the inputs have the same number
+      of columns (and compatible types).
+    * ``JOIN`` queries may break due to new column name conflicts, e.g. the
+      query references a column ``c`` which initially existed in only one input
+      table but a column of the same name is added to another table.
+    * ``CREATE TABLE (<<column schema>>) AS SELECT *``
 
 
     .. code-block:: sql
@@ -45,8 +46,9 @@ class Rule_L044(BaseRule):
         UNION
         SELECT a, b FROM t
 
-    | **Best practice**
-    | Somewhere along the "path" to the source data, specify columns explicitly.
+    **Best practice**
+
+    Somewhere along the "path" to the source data, specify columns explicitly.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L045.py b/src/sqlfluff/rules/L045.py
index a1fd078d567..b6c635e9742 100644
--- a/src/sqlfluff/rules/L045.py
+++ b/src/sqlfluff/rules/L045.py
@@ -8,9 +8,10 @@
 class Rule_L045(BaseRule):
     """Query defines a CTE (common-table expression) but does not use it.
 
-    | **Anti-pattern**
-    | Defining a CTE that is not used by the query is harmless, but it means
-    | the code is unnecessary and could be removed.
+    **Anti-pattern**
+
+    Defining a CTE that is not used by the query is harmless, but it means
+    the code is unnecessary and could be removed.
 
     .. code-block:: sql
 
@@ -26,8 +27,9 @@ class Rule_L045(BaseRule):
         SELECT *
         FROM cte1
 
-    | **Best practice**
-    | Remove unused CTEs.
+    **Best practice**
+
+    Remove unused CTEs.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L046.py b/src/sqlfluff/rules/L046.py
index 81089be4d96..bc75d92d3f1 100644
--- a/src/sqlfluff/rules/L046.py
+++ b/src/sqlfluff/rules/L046.py
@@ -7,18 +7,20 @@
 class Rule_L046(BaseRule):
     """Jinja tags should have a single whitespace on either side.
 
-    | **Anti-pattern**
-    | Jinja tags with either no whitespace or very long whitespace
-    | are hard to read.
+    **Anti-pattern**
+
+    Jinja tags with either no whitespace or very long whitespace
+    are hard to read.
 
     .. code-block:: sql
        :force:
 
         SELECT {{    a     }} from {{ref('foo')}}
 
-    | **Best practice**
-    | A single whitespace surrounding Jinja tags, alternatively
-    | longer gaps containing newlines are acceptable.
+    **Best practice**
+
+    A single whitespace surrounding Jinja tags, alternatively
+    longer gaps containing newlines are acceptable.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L047.py b/src/sqlfluff/rules/L047.py
index 0db6f80fe3b..754d37483b3 100644
--- a/src/sqlfluff/rules/L047.py
+++ b/src/sqlfluff/rules/L047.py
@@ -15,8 +15,8 @@ class Rule_L047(BaseRule):
     """Use consistent syntax to express "count number of rows".
 
     Note:
-        If both `prefer_count_1` and `prefer_count_0` are set to true
-        then `prefer_count_1` has precedence.
+        If both ``prefer_count_1`` and ``prefer_count_0`` are set to true
+        then ``prefer_count_1`` has precedence.
 
     ``COUNT(*)``, ``COUNT(1)``, and even ``COUNT(0)`` are equivalent syntaxes
     in many SQL engines due to optimizers interpreting these instructions as
@@ -36,7 +36,7 @@ class Rule_L047(BaseRule):
 
     .. _ANSI-92: http://msdn.microsoft.com/en-us/library/ms175997.aspx
 
-    | **Anti-pattern**
+    **Anti-pattern**
 
     .. code-block:: sql
 
@@ -44,9 +44,10 @@ class Rule_L047(BaseRule):
             count(1)
         from table_a
 
-    | **Best practice**
-    | Use ``count(*)`` unless specified otherwise by config ``prefer_count_1``,
-    | or ``prefer_count_0`` as preferred.
+    **Best practice**
+
+    Use ``count(*)`` unless specified otherwise by config ``prefer_count_1``,
+    or ``prefer_count_0`` as preferred.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L048.py b/src/sqlfluff/rules/L048.py
index ba849d8d835..0665301eea0 100644
--- a/src/sqlfluff/rules/L048.py
+++ b/src/sqlfluff/rules/L048.py
@@ -12,9 +12,10 @@
 class Rule_L048(Rule_L006):
     """Quoted literals should be surrounded by a single whitespace.
 
-    | **Anti-pattern**
-    | In this example, there is a space missing space between the string
-    | ``'foo'`` and the keyword ``AS``.
+    **Anti-pattern**
+
+    In this example, there is a space missing space between the string
+    ``'foo'`` and the keyword ``AS``.
 
     .. code-block:: sql
 
@@ -23,8 +24,9 @@ class Rule_L048(Rule_L006):
         FROM foo
 
 
-    | **Best practice**
-    | Keep a single space.
+    **Best practice**
+
+    Keep a single space.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L049.py b/src/sqlfluff/rules/L049.py
index 3ceb220dd11..5b216125830 100644
--- a/src/sqlfluff/rules/L049.py
+++ b/src/sqlfluff/rules/L049.py
@@ -11,8 +11,9 @@
 class Rule_L049(Rule_L006):
     """Comparisons with NULL should use "IS" or "IS NOT".
 
-    | **Anti-pattern**
-    | In this example, the ``=`` operator is used to check for ``NULL`` values.
+    **Anti-pattern**
+
+    In this example, the ``=`` operator is used to check for ``NULL`` values.
 
     .. code-block:: sql
 
@@ -22,8 +23,9 @@ class Rule_L049(Rule_L006):
         WHERE a = NULL
 
 
-    | **Best practice**
-    | Use ``IS`` or ``IS NOT`` to check for ``NULL`` values.
+    **Best practice**
+
+    Use ``IS`` or ``IS NOT`` to check for ``NULL`` values.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L050.py b/src/sqlfluff/rules/L050.py
index 09500c86465..fd8d70006f4 100644
--- a/src/sqlfluff/rules/L050.py
+++ b/src/sqlfluff/rules/L050.py
@@ -11,9 +11,10 @@
 class Rule_L050(BaseRule):
     """Files must not begin with newlines or whitespace.
 
-    | **Anti-pattern**
-    | The content in file begins with newlines or whitespace. The ``^``
-    | represents the beginning of the file.
+    **Anti-pattern**
+
+    The content in file begins with newlines or whitespace. The ``^``
+    represents the beginning of the file.
 
     .. code-block:: sql
        :force:
@@ -32,9 +33,10 @@ class Rule_L050(BaseRule):
         FROM
         ••••foo
 
-    | **Best practice**
-    | Start file on either code or comment. (The ``^`` represents the beginning
-    | of the file.)
+    **Best practice**
+
+    Start file on either code or comment. (The ``^`` represents the beginning
+    of the file.)
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L051.py b/src/sqlfluff/rules/L051.py
index 011f124841b..68851effc36 100644
--- a/src/sqlfluff/rules/L051.py
+++ b/src/sqlfluff/rules/L051.py
@@ -10,8 +10,9 @@
 class Rule_L051(BaseRule):
     """``INNER JOIN`` must be fully qualified.
 
-    | **Anti-pattern**
-    | Lone ``JOIN`` is used.
+    **Anti-pattern**
+
+    Lone ``JOIN`` is used.
 
     .. code-block:: sql
        :force:
@@ -21,8 +22,9 @@ class Rule_L051(BaseRule):
         FROM bar
         JOIN baz;
 
-    | **Best practice**
-    | Use ``INNER JOIN`` rather than ``JOIN``.
+    **Best practice**
+
+    Use ``INNER JOIN`` rather than ``JOIN``.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L052.py b/src/sqlfluff/rules/L052.py
index 3bf477a3cee..d4a51135489 100644
--- a/src/sqlfluff/rules/L052.py
+++ b/src/sqlfluff/rules/L052.py
@@ -18,9 +18,10 @@
 class Rule_L052(BaseRule):
     """Statements must end with a semi-colon.
 
-    | **Anti-pattern**
-    | A statement is not immediately terminated with a semi-colon, the • represents
-    | space.
+    **Anti-pattern**
+
+    A statement is not immediately terminated with a semi-colon, the • represents
+    space.
 
     .. code-block:: sql
        :force:
@@ -35,8 +36,9 @@ class Rule_L052(BaseRule):
             b
         FROM bar••;
 
-    | **Best practice**
-    | Immediately terminate the statement with a semi-colon.
+    **Best practice**
+
+    Immediately terminate the statement with a semi-colon.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L053.py b/src/sqlfluff/rules/L053.py
index afebe42ed5b..1ce21e9eecf 100644
--- a/src/sqlfluff/rules/L053.py
+++ b/src/sqlfluff/rules/L053.py
@@ -9,8 +9,9 @@
 class Rule_L053(BaseRule):
     """Top-level statements should not be wrapped in brackets.
 
-    | **Anti-pattern**
-    | A top-level statement is wrapped in brackets.
+    **Anti-pattern**
+
+    A top-level statement is wrapped in brackets.
 
     .. code-block:: sql
        :force:
@@ -25,8 +26,9 @@ class Rule_L053(BaseRule):
             foo
         FROM (SELECT * FROM bar))
 
-    | **Best practice**
-    | Don't wrap top-level statements in brackets.
+    **Best practice**
+
+    Don't wrap top-level statements in brackets.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L054.py b/src/sqlfluff/rules/L054.py
index 18ef7d8304d..c8272801662 100644
--- a/src/sqlfluff/rules/L054.py
+++ b/src/sqlfluff/rules/L054.py
@@ -12,11 +12,13 @@
 class Rule_L054(BaseRule):
     """Inconsistent column references in ``GROUP BY/ORDER BY`` clauses.
 
-    Note: ORDER BY clauses from WINDOW clauses are ignored by this rule.
+    .. note::
+       ``ORDER BY`` clauses from ``WINDOW`` clauses are ignored by this rule.
 
-    | **Anti-pattern**
-    | A mix of implicit and explicit column references are used in a ``GROUP BY``
-    | clause.
+    **Anti-pattern**
+
+    A mix of implicit and explicit column references are used in a ``GROUP BY``
+    clause.
 
     .. code-block:: sql
        :force:
@@ -39,8 +41,9 @@ class Rule_L054(BaseRule):
         ORDER BY
             1, bar;
 
-    | **Best practice**
-    | Reference all ``GROUP BY/ORDER BY`` columns either by name or by position.
+    **Best practice**
+
+    Reference all ``GROUP BY``/``ORDER BY`` columns either by name or by position.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L055.py b/src/sqlfluff/rules/L055.py
index 257c1e6a2dd..d75dabec5bd 100644
--- a/src/sqlfluff/rules/L055.py
+++ b/src/sqlfluff/rules/L055.py
@@ -7,8 +7,9 @@
 class Rule_L055(BaseRule):
     """Use ``LEFT JOIN`` instead of ``RIGHT JOIN``.
 
-    | **Anti-pattern**
-    | ``RIGHT JOIN`` is used.
+    **Anti-pattern**
+
+    ``RIGHT JOIN`` is used.
 
     .. code-block:: sql
        :force:
@@ -20,8 +21,9 @@ class Rule_L055(BaseRule):
         RIGHT JOIN bar
             ON foo.bar_id = bar.id;
 
-    | **Best practice**
-    | Refactor and use ``LEFT JOIN`` instead.
+    **Best practice**
+
+    Refactor and use ``LEFT JOIN`` instead.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L056.py b/src/sqlfluff/rules/L056.py
index a2975e24cf2..208542f4c74 100644
--- a/src/sqlfluff/rules/L056.py
+++ b/src/sqlfluff/rules/L056.py
@@ -7,10 +7,11 @@
 class Rule_L056(BaseRule):
     r"""``SP_`` prefix should not be used for user-defined stored procedures in T-SQL.
 
-    | **Anti-pattern**
-    | The ``SP_`` prefix is used to identify system procedures and
-    | can adversely affect performance of the user-defined stored procedure.
-    | It can also break system procedures if there is a naming conflict.
+    **Anti-pattern**
+
+    The ``SP_`` prefix is used to identify system procedures and can adversely
+    affect performance of the user-defined stored procedure. It can also break
+    system procedures if there is a naming conflict.
 
     .. code-block:: sql
        :force:
@@ -23,8 +24,9 @@ class Rule_L056(BaseRule):
             CaseOutput
         FROM table1
 
-    | **Best practice**
-    | Use a different name for the stored procedure.
+    **Best practice**
+
+    Use a different name for the stored procedure.
 
     .. code-block:: sql
        :force:
diff --git a/src/sqlfluff/rules/L057.py b/src/sqlfluff/rules/L057.py
index 26fb5599b2a..6330a652419 100644
--- a/src/sqlfluff/rules/L057.py
+++ b/src/sqlfluff/rules/L057.py
@@ -13,8 +13,9 @@
 class Rule_L057(BaseRule):
     """Do not use special characters in identifiers.
 
-    | **Anti-pattern**
-    | Using special characters within identifiers when creating or aliasing objects.
+    **Anti-pattern**
+
+    Using special characters within identifiers when creating or aliasing objects.
 
     .. code-block:: sql
 
@@ -26,8 +27,9 @@ class Rule_L057(BaseRule):
             Number# INT
         )
 
-    | **Best practice**
-    | Identifiers should include only alphanumerics and underscores.
+    **Best practice**
+
+    Identifiers should include only alphanumerics and underscores.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L058.py b/src/sqlfluff/rules/L058.py
index 5cdbf22adbc..2402a6a6678 100644
--- a/src/sqlfluff/rules/L058.py
+++ b/src/sqlfluff/rules/L058.py
@@ -10,8 +10,9 @@
 class Rule_L058(BaseRule):
     """Nested ``CASE`` statement in ``ELSE`` clause could be flattened.
 
-    | **Anti-pattern**
-    | In this example, the outer ``CASE``'s ``ELSE`` is an unnecessary other ``CASE``.
+    **Anti-pattern**
+
+    In this example, the outer ``CASE``'s ``ELSE`` is an unnecessary other ``CASE``.
 
     .. code-block:: sql
 
@@ -25,8 +26,9 @@ class Rule_L058(BaseRule):
           END as sound
         FROM mytable
 
-    | **Best practice**
-    | Move the body of the inner ``CASE`` to the end of the outer one.
+    **Best practice**
+
+    Move the body of the inner ``CASE`` to the end of the outer one.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L059.py b/src/sqlfluff/rules/L059.py
index 1f3a75b4d8a..a9bc0974b5e 100644
--- a/src/sqlfluff/rules/L059.py
+++ b/src/sqlfluff/rules/L059.py
@@ -13,16 +13,18 @@
 class Rule_L059(BaseRule):
     """Unnecessary quoted identifier.
 
-    | **Anti-pattern**
-    | In this example, a valid unquoted identifier,
-    | that is also not a reserved keyword, is needlessly quoted.
+    **Anti-pattern**
+
+    In this example, a valid unquoted identifier,
+    that is also not a reserved keyword, is needlessly quoted.
 
     .. code-block:: sql
 
         SELECT 123 as "foo"
 
-    | **Best practice**
-    | Use unquoted identifiers where possible.
+    **Best practice**
+
+    Use unquoted identifiers where possible.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L060.py b/src/sqlfluff/rules/L060.py
index 8a9962081a9..3d0510d7708 100644
--- a/src/sqlfluff/rules/L060.py
+++ b/src/sqlfluff/rules/L060.py
@@ -11,8 +11,9 @@
 class Rule_L060(BaseRule):
     """Use ``COALESCE`` instead of ``IFNULL`` or ``NVL``.
 
-    | **Anti-pattern**
-    | ``IFNULL`` or ``NVL`` are used to fill ``NULL`` values.
+    **Anti-pattern**
+
+    ``IFNULL`` or ``NVL`` are used to fill ``NULL`` values.
 
     .. code-block:: sql
 
@@ -22,13 +23,14 @@ class Rule_L060(BaseRule):
         SELECT nvl(foo, 0) AS bar,
         FROM baz;
 
-    | **Best practice**
-    | Use ``COALESCE`` instead.
-    | ``COALESCE`` is universally supported,
-    | whereas Redshift doesn't support ``IFNULL``
-    | and BigQuery doesn't support ``NVL``.
-    | Additionally ``COALESCE`` is more flexible
-    | and accepts an arbitrary number of arguments.
+    **Best practice**
+
+    Use ``COALESCE`` instead.
+    ``COALESCE`` is universally supported,
+    whereas Redshift doesn't support ``IFNULL``
+    and BigQuery doesn't support ``NVL``.
+    Additionally ``COALESCE`` is more flexible
+    and accepts an arbitrary number of arguments.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L061.py b/src/sqlfluff/rules/L061.py
index 1e196ba15ec..93d5bef140a 100644
--- a/src/sqlfluff/rules/L061.py
+++ b/src/sqlfluff/rules/L061.py
@@ -12,16 +12,18 @@
 class Rule_L061(BaseRule):
     """Use ``!=`` instead of ``<>`` for "not equal to" comparisons.
 
-    | **Anti-pattern**
-    | ``<>`` means ``not equal`` but doesn't sound like this when we say it out loud.
+    **Anti-pattern**
+
+    ``<>`` means ``not equal`` but doesn't sound like this when we say it out loud.
 
     .. code-block:: sql
 
         SELECT * FROM X WHERE 1 <> 2;
 
-    | **Best practice**
-    | Use ``!=`` instead because it's sounds more natural and is more common in other
-    | programming languages.
+    **Best practice**
+
+    Use ``!=`` instead because it's sounds more natural and is more common in other
+    programming languages.
 
     .. code-block:: sql
 
diff --git a/src/sqlfluff/rules/L062.py b/src/sqlfluff/rules/L062.py
index 5921f15c45b..0d2a2de33f2 100644
--- a/src/sqlfluff/rules/L062.py
+++ b/src/sqlfluff/rules/L062.py
@@ -15,7 +15,7 @@ class Rule_L062(BaseRule):
 
     This block list is case insensitive.
 
-    Example use cases:
+    **Example use cases**
 
     * We prefer ``BOOL`` over ``BOOLEAN`` and there is no existing rule to enforce
       this. Until such a rule is written, we can add ``BOOLEAN`` to the deny list
@@ -24,17 +24,19 @@ class Rule_L062(BaseRule):
       in future. We can add that to the denylist and then add a ``-- noqa: L062`` for
       the few exceptions that still need to be in the code base for now.
 
-    | **Anti-pattern**
-    | If the ``blocked_words`` config is set to ``deprecated_table,bool`` then the
-    | following will flag:
+    **Anti-pattern**
+
+    If the ``blocked_words`` config is set to ``deprecated_table,bool`` then the
+    following will flag:
 
     .. code-block:: sql
 
         SELECT * FROM deprecated_table WHERE 1 = 1;
         CREATE TABLE myschema.t1 (a BOOL);
 
-    | **Best practice**
-    | Do not used any blocked words:
+    **Best practice**
+
+    Do not used any blocked words:
 
     .. code-block:: sql
 
diff --git a/test/core/rules/docstring_test.py b/test/core/rules/docstring_test.py
index 81c64df535c..91ae8b999a4 100644
--- a/test/core/rules/docstring_test.py
+++ b/test/core/rules/docstring_test.py
@@ -3,9 +3,10 @@
 
 from sqlfluff import lint
 from sqlfluff.core.plugin.host import get_plugin_manager
+from sqlfluff.core.rules.doc_decorators import is_configurable
 
-KEYWORD_ANTI = "\n    | **Anti-pattern**"
-KEYWORD_BEST = "\n    | **Best practice**"
+KEYWORD_ANTI = "    **Anti-pattern**"
+KEYWORD_BEST = "    **Best practice**"
 KEYWORD_CODE_BLOCK = "\n    .. code-block:: sql\n"
 
 
@@ -22,10 +23,10 @@ def test_content_count(content, min_count):
     for plugin_rules in get_plugin_manager().hook.get_rules():
         for rule in plugin_rules:
             if rule._check_docstring is True:
-                assert (
-                    rule.__doc__.count(content) >= min_count
-                ), f"{rule.__name__} content {content} does not occur at less "
-                f"{min_count} times"
+                assert rule.__doc__.count(content) >= min_count, (
+                    f"{rule.__name__} content {content} does not occur at least "
+                    f"{min_count} times"
+                )
 
 
 def test_keyword_anti_before_best():
@@ -35,8 +36,21 @@ def test_keyword_anti_before_best():
             if rule._check_docstring is True:
                 assert rule.__doc__.index(KEYWORD_ANTI) < rule.__doc__.index(
                     KEYWORD_BEST
-                ), f"{rule.__name__} keyword {KEYWORD_BEST} appears before "
-                f"{KEYWORD_ANTI}"
+                ), (
+                    f"{rule.__name__} keyword {KEYWORD_BEST} appears before "
+                    f"{KEYWORD_ANTI}"
+                )
+
+
+def test_config_decorator():
+    """Test rules with config_keywords have the @document_configuration decorator."""
+    for plugin_rules in get_plugin_manager().hook.get_rules():
+        for rule in plugin_rules:
+            if hasattr(rule, "config_keywords"):
+                assert is_configurable(rule), (
+                    f"Rule {rule.__name__} has config but is not decorated with "
+                    "@document_configuration to display that config."
+                )
 
 
 def test_backtick_replace():


Code review comments:
diff_hunk: @@ -37,9 +37,10 @@ class Rule_L014(Rule_L010):
 
     The functionality for this rule is inherited from :obj:`Rule_L010`.
path: src/sqlfluff/rules/L014.py
text: @user1:
I wonder if we should remove this (and all other references to rules inheriting from one another).

@author:
Agreed. All 3 are gone.

diff_hunk: @@ -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 spaces (default).
path: src/sqlfluff/rules/L004.py
text: @user1:
Adding code formatting. Also note that the setting is called `space`, not `spaces`.
```suggestion
    Using tabs instead of spaces when ``indent_unit`` config set to ``space`` (default).
```

diff_hunk: @@ -9,17 +9,19 @@
 class Rule_L017(BaseRule):
     """Function name not immediately followed by bracket.
path: src/sqlfluff/rules/L017.py
text: @user1:
Suggest changing the wording, as "bracket" is internal parser terminology. We should also update the wording on line 33.
```suggestion
    """Function name not immediately followed by parenthesis.
```

@author:
Think it's more common in UK English. But happy to accept for consistency.

diff_hunk: @@ -29,8 +30,9 @@ class Rule_L040(Rule_L010):
             false
         from foo
 
-    | **Best practice**
-    | Ensure all literal null/true/false literals cases are used consistently
+    **Best practice**
+
+    Ensure all literal ``null``/``true``/``false`` literals cases are used consistently
path: src/sqlfluff/rules/L040.py
text: @user1:
The wording here is weird.
```suggestion
    Ensure all literal ``null``/``true``/``false`` literals are consistently upper or lower case
```

diff_hunk: @@ -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**
+
+    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.
path: src/sqlfluff/rules/L007.py
text: @user1:
```suggestion
    In this example, ``operator_new_lines = after`` (or unspecified, as this is the default).
    The operator ``+`` should not be at the end of the second line.
```

@author:
```suggestion
    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.
```

diff_hunk: @@ -1,28 +1,33 @@
 """Implementation of Rule L012."""
 
 from sqlfluff.rules.L011 import Rule_L011
+from sqlfluff.core.rules.doc_decorators import document_configuration
 
 
+@document_configuration
 class Rule_L012(Rule_L011):
     """Implicit/explicit aliasing of columns.
 
     Aliasing of columns to follow preference
-    (explicit using an `AS` clause is default).
+    (explicit using an ``AS`` clause is default).
 
-    NB: This rule inherits its functionality from :obj:`Rule_L011` but is
-    separate so that they can be enabled and disabled separately.
+    .. note::
+       This rule inherits its functionality from :obj:`Rule_L011` but is
+       separate so that they can be enabled and disabled separately.
path: src/sqlfluff/rules/L012.py
text: @user1:
I wonder if we should remove this note. Do users care about this? They may not be Python developers, so the word "inherit" may not be familiar to them, also.

@author:
Agreed. It's gone!

diff_hunk: @@ -12,18 +12,20 @@
 class Rule_L015(BaseRule):
     """``DISTINCT`` used with parentheses.
 
-    | **Anti-pattern**
-    | In this example, parenthesis are not needed and confuse
-    | ``DISTINCT`` with a function. The parenthesis can also be misleading
-    | in which columns they apply to.
+    **Anti-pattern**
+
+    In this example, parenthesis are not needed and confuse
+    ``DISTINCT`` with a function. The parenthesis can also be misleading
+    in which columns they apply to.
 
     .. code-block:: sql
 
         SELECT DISTINCT(a), b FROM foo
 
-    | **Best practice**
-    | Remove parenthesis to be clear that the ``DISTINCT`` applies to
-    | both columns.
+    **Best practice**
+
+    Remove parenthesis to be clear that the ``DISTINCT`` applies to
path: src/sqlfluff/rules/L015.py
text: @user1:
```suggestion
    Remove parentheses to be clear that the ``DISTINCT`` applies to
```

diff_hunk: @@ -11,9 +11,10 @@
 class Rule_L050(BaseRule):
     """Files must not begin with newlines or whitespace.
 
-    | **Anti-pattern**
-    | The content in file begins with newlines or whitespace. The ``^``
-    | represents the beginning of the file.
+    **Anti-pattern**
+
+    The content in file begins with newlines or whitespace. The ``^``
path: src/sqlfluff/rules/L050.py
text: @user1:
```suggestion
    The file begins with newlines or whitespace. The ``^``
```

diff_hunk: @@ -10,8 +10,9 @@
 class Rule_L058(BaseRule):
     """Nested ``CASE`` statement in ``ELSE`` clause could be flattened.
 
-    | **Anti-pattern**
-    | In this example, the outer ``CASE``'s ``ELSE`` is an unnecessary other ``CASE``.
+    **Anti-pattern**
+
+    In this example, the outer ``CASE``'s ``ELSE`` is an unnecessary other ``CASE``.
path: src/sqlfluff/rules/L058.py
text: @user1:
```suggestion
    In this example, the outer ``CASE``'s ``ELSE`` is an unnecessary, nested ``CASE``.
```

diff_hunk: @@ -12,16 +12,18 @@
 class Rule_L061(BaseRule):
     """Use ``!=`` instead of ``<>`` for "not equal to" comparisons.
 
-    | **Anti-pattern**
-    | ``<>`` means ``not equal`` but doesn't sound like this when we say it out loud.
+    **Anti-pattern**
+
+    ``<>`` means ``not equal`` but doesn't sound like this when we say it out loud.
 
     .. code-block:: sql
 
         SELECT * FROM X WHERE 1 <> 2;
 
-    | **Best practice**
-    | Use ``!=`` instead because it's sounds more natural and is more common in other
-    | programming languages.
+    **Best practice**
+
+    Use ``!=`` instead because it's sounds more natural and is more common in other
path: src/sqlfluff/rules/L061.py
text: @user1:
```suggestion
    Use ``!=`` instead because its sounds more natural and is more common in other
```

diff_hunk: @@ -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 space between the operator and ``b``.
path: src/sqlfluff/rules/L006.py
text: @user1:
Removing duplicate word.
```suggestion
    In this example, there is a space missing between the operator and ``b``.
```