Create FAQ documentation (GH-2247)

This commit creates a Frequently Asked Questions document for our users
to read. Hopefully they actually read it too. Items included are:
Black's non-API, AST safety, style stability, file discovery, Flake8
disagreements and Python 2 support. Hopefully I've got the answers
down in general.

Commit history before merge:

* Create FAQ
* Address feedback
* Move to single markdown file
* Minor wording improvements
* Add changelog entry

diff --git a/CHANGES.md b/CHANGES.md
index 34fa1a2092a89827d89296fa9a2dbd9eaa9c8719..22939e38c122d2e5a3e35c8a81fc22f9f8706e39 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,6 +22,7 @@
 
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
+- Add new Frequently Asked Questions page (#2247)
 
 ## 21.5b1
 

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index c06c40a2dfceaf7e58629a5de91b8a364a541d12..eacd69c15a09463d529d9fe1172718bd38da3a32 100644 (file)
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -36,3 +36,9 @@ _:-ms-fullscreen,
     -ms-overflow-style: none;
   }
 }
+
+/* Nicer style for local document toc */
+.contents.topic {
+  background: none;
+  border: none;
+}

diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644 (file)
index 0000000..46e4598
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,52 @@
+# Frequently Asked Questions
+
+The most common questions and issues users face are aggregated to this FAQ.
+
+```{contents}
+:local:
+:backlinks: none
+```
+
+## Does Black have an API?
+
+Not yet. _Black_ is fundamentally a command line tool. Many
+[integrations](integrations/index.rst) are provided, but a Python interface is not one
+of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
+though.
+
+## Is Black safe to use?
+
+Yes, for the most part. _Black_ is strictly about formatting, nothing else. But because
+_Black_ is still in [beta](index.rst), some edges are still a bit rough. To combat
+issues, the equivalence of code after formatting is
+[checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
+limited special cases where the code is allowed to differ. If issues are found, an error
+is raised and the file is left untouched.
+
+## How stable is Black's style?
+
+Quite stable. _Black_ aims to enforce one style and one style only, with some room for
+pragmatism. However, _Black_ is still in beta so style changes are both planned and
+still proposed on the issue tracker. See
+[The Black Code Style](the_black_code_style/index.rst) for more details.
+
+## Why is my file not formatted?
+
+Most likely because it is ignored in `.gitignore` or excluded with configuration. See
+[file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
+for details.
+
+## Why are Flake8's E203 and W503 violated?
+
+Because they go against PEP 8. E203 falsely triggers on list
+[slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
+readability because operators are misaligned. Disable W503 and enable the
+disabled-by-default counterpart W504. E203 should be disabled while changes are still
+[discussed](https://github.com/PyCQA/pycodestyle/issues/373).
+
+## Does Black support Python 2?
+
+For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
+to format Python 2 files too! There are no current plans to drop support, but most
+likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though,
+Python 3.6 or newer is required.

diff --git a/docs/index.rst b/docs/index.rst
index 2b85cddd3c06d87b91250c972ec6a93184c10dbb..53857995ec6ad759eac0b61bcbd545bbe4806e97 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -97,6 +97,7 @@ Contents
    usage_and_configuration/index
    integrations/index
    guides/index
+   faq
 
 .. toctree::
    :maxdepth: 3