Draft for Black 2023 stable style (#3418)

[etc/vim.git] / docs / usage_and_configuration / the_basics.md

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 48dda3ba036e9ff57dbb54c3f4a687aac7ef8dd1..9dc5277c61ead021047ea005cae0bb81bdeb2890 100644 (file)
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -40,6 +40,9 @@ so style options are deliberately limited and rarely added.
 
 </details>
 
+Note that all command-line options listed above can also be configured using a
+`pyproject.toml` file (more on that below).
+
 ### Code input alternatives
 
 #### Standard Input
@@ -76,6 +79,8 @@ _Black_ to just tell you what it _would_ do without actually rewriting the Pytho
 There's two variations to this mode that are independently enabled by their respective
 flags. Both variations can be enabled at once.
 
+(labels/exit-code)=
+
 #### Exit code
 
 Passing `--check` will make _Black_ exit with:
@@ -173,7 +178,7 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
-black, version 22.1.0
+black, version 22.12.0
 ```
 
 An option to require a specific version to be running is also provided.
@@ -204,9 +209,10 @@ code in compliance with many other _Black_ formatted projects.
 
 [PEP 518](https://www.python.org/dev/peps/pep-0518/) defines `pyproject.toml` as a
 configuration file to store build system requirements for Python projects. With the help
-of tools like [Poetry](https://python-poetry.org/) or
-[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
-`setup.py` and `setup.cfg` files.
+of tools like [Poetry](https://python-poetry.org/),
+[Flit](https://flit.readthedocs.io/en/latest/), or
+[Hatch](https://hatch.pypa.io/latest/) it can fully replace the need for `setup.py` and
+`setup.cfg` files.
 
 ### Where _Black_ looks for the file
 
@@ -259,10 +265,14 @@ expressions by Black. Use `[ ]` to denote a significant space character.
 line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
+# 'extend-exclude' excludes files or directories in addition to the defaults
 extend-exclude = '''
 # A regex preceded with ^/ will apply only to files and directories
 # in the root of the project.
-^/foo.py  # exclude a file named foo.py in the root of the project (in addition to the defaults)
+(
+  ^/foo.py    # exclude a file named foo.py in the root of the project
+  | .*_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
+)
 '''
 ```
 
@@ -280,9 +290,6 @@ file hierarchy.
 
 ## Next steps
 
-You've probably noted that not all of the options you can pass to _Black_ have been
-covered. Don't worry, the rest will be covered in a later section.
-
 A good next step would be configuring auto-discovery so `black .` is all you need
 instead of laborously listing every file or directory. You can get started by heading
 over to [File collection and discovery](./file_collection_and_discovery.md).