Upgrade docs to Sphinx 3+ and add doc build test (#1613)

[etc/vim.git] / docs / compatible_configs.md

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index e8267435323adf26c797217398f8cc5a32507b48..25e959e328110a12b7dc90df022b4bc9b1444a1e 100644 (file)
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -6,6 +6,10 @@ linters and type checkers. Some of them need a bit of tweaking to resolve the co
 Listed below are _Black_ compatible configurations in various formats for the common
 tools out there.
 
 Listed below are _Black_ compatible configurations in various formats for the common
 tools out there.
 

+**Please note** that _Black_ only supports the TOML file format for its configuration
+(e.g. `pyproject.toml`). The provided examples are to only configure their corresponding
+tools, using **their** supported file formats.
+

 ## isort
 
 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
 ## isort
 
 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.


@@ -19,13 +23,14 @@ multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True

+ensure_newline_before_comments = True

 line_length = 88
 ```
 
 ### Why those options above?
 
 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own
 line_length = 88
 ```
 
 ### Why those options above?
 
 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own

-indented line. If that still doesn't fit the bill, it will put all of them in seperate
+indented line. If that still doesn't fit the bill, it will put all of them in separate

 lines and put a trailing comma. A more detailed explanation of this behaviour can be
 [found here](https://github.com/psf/black#how-black-wraps-lines).
 
 lines and put a trailing comma. A more detailed explanation of this behaviour can be
 [found here](https://github.com/psf/black#how-black-wraps-lines).
 


@@ -58,7 +63,15 @@ The option `force_grid_wrap = 0` is just to tell isort to only wrap imports that
 the `line_length` limit.
 
 Finally, isort should be told to wrap imports when they surpass _Black_'s default limit
 the `line_length` limit.
 
 Finally, isort should be told to wrap imports when they surpass _Black_'s default limit

-of 88 characters via `line_length = 88`.
+of 88 characters via `line_length = 88` as well as
+`ensure_newline_before_comments = True` to ensure spacing import sections with comments
+works the same as with _Black_.
+
+**Please note** `ensure_newline_before_comments = True` only works since isort >= 5 but
+does not break older versions so you can keep it if you are running previous versions.
+If only isort >= 5 is used you can add `profile = black` instead of all the options
+since [profiles](https://timothycrosley.github.io/isort/docs/configuration/profiles/)
+are available and do the configuring for you.

 
 ### Formats
 
 
 ### Formats
 


@@ -71,6 +84,7 @@ multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True

+ensure_newline_before_comments = True

 line_length = 88
 ```
 
 line_length = 88
 ```
 


@@ -85,6 +99,7 @@ multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True

+ensure_newline_before_comments = True

 line_length = 88
 ```
 
 line_length = 88
 ```
 


@@ -99,6 +114,7 @@ multi_line_output = 3
 include_trailing_comma = true
 force_grid_wrap = 0
 use_parentheses = true
 include_trailing_comma = true
 force_grid_wrap = 0
 use_parentheses = true

+ensure_newline_before_comments = true

 line_length = 88
 ```
 
 line_length = 88
 ```
 


@@ -113,6 +129,7 @@ multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True

+ensure_newline_before_comments = True

 line_length = 88
 ```
 
 line_length = 88
 ```
 


@@ -224,7 +241,7 @@ characters via `max-line-length = 88`.
 <details>
 <summary>pylintrc</summary>
 
 <details>
 <summary>pylintrc</summary>
 

-```rc
+```ini

 [MESSAGES CONTROL]
 disable = C0330, C0326
 
 [MESSAGES CONTROL]
 disable = C0330, C0326