Document some culprits with pre-commit (#1783)

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

diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
deleted file mode 120000 (symlink)
index 57c866401ff3426ce65b38670ae4e04d9aa6a251..0000000000000000000000000000000000000000
--- a/docs/pyproject_toml.md
+++ /dev/null
@@ -1 +0,0 @@
-_build/generated/pyproject_toml.md
\ No newline at end of file

diff --git a/docs/pyproject_toml.md b/docs/pyproject_toml.md
new file mode 100644 (file)
index 0000000000000000000000000000000000000000..cd313452b1e7f75d3748ea5a1a5e4ad2dcdd8816
--- /dev/null
+++ b/docs/pyproject_toml.md
@@ -0,0 +1,88 @@
+[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
+
+# pyproject.toml
+
+_Black_ is able to read project-specific default values for its command line options
+from a `pyproject.toml` file. This is especially useful for specifying custom
+`--include` and `--exclude` patterns for your project.
+
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
+"No". _Black_ is all about sensible defaults.
+
+## What on Earth is a `pyproject.toml` file?
+
+[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.
+
+## Where _Black_ looks for the file
+
+By default _Black_ looks for `pyproject.toml` starting from the common base directory of
+all files and directories passed on the command line. If it's not there, it looks in
+parent directories. It stops looking when it finds the file, or a `.git` directory, or a
+`.hg` directory, or the root of the file system, whichever comes first.
+
+If you're formatting standard input, _Black_ will look for configuration starting from
+the current working directory.
+
+You can also explicitly specify the path to a particular file that you want with
+`--config`. In this situation _Black_ will not look for any other file.
+
+If you're running with `--verbose`, you will see a blue message if a file was found and
+used.
+
+Please note `blackd` will not use `pyproject.toml` configuration.
+
+## Configuration format
+
+As the file extension suggests, `pyproject.toml` is a
+[TOML](https://github.com/toml-lang/toml) file. It contains separate sections for
+different tools. _Black_ is using the `[tool.black]` section. The option keys are the
+same as long names of options on the command line.
+
+Note that you have to use single-quoted strings in TOML for regular expressions. It's
+the equivalent of r-strings in Python. Multiline strings are treated as verbose regular
+expressions by Black. Use `[ ]` to denote a significant space character.
+
+<details>
+<summary>Example <code>pyproject.toml</code></summary>
+
+```toml
+[tool.black]
+line-length = 88
+target-version = ['py37']
+include = '\.pyi?$'
+exclude = '''
+
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | buck-out
+    | build
+    | dist
+  )/
+  | foo.py           # also separately exclude a file named foo.py in
+                     # the root of the project
+)
+'''
+```
+
+</details>
+
+## Lookup hierarchy
+
+Command-line options have defaults that you can see in `--help`. A `pyproject.toml` can
+override those defaults. Finally, options provided by the user on the command line
+override both.
+
+_Black_ will only ever use one `pyproject.toml` file during an entire run. It doesn't
+look for multiple files, and doesn't compose configuration from different levels of the
+file hierarchy.