Unverified Commit 04518c38 authored by Felix Hildén's avatar Felix Hildén Committed by GitHub
Browse files

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
parent 3759b856
Loading
Loading
Loading
Loading
+1 −0
Changes for CHANGES.md: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -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

+6 −0
Changes for docs/_static/custom.css: 6 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -36,3 +36,9 @@ _:-ms-fullscreen,
    -ms-overflow-style: none;
  }
}

/* Nicer style for local document toc */
.contents.topic {
  background: none;
  border: none;
}

docs/faq.md

0 → 100644
+52 −0
Changes for docs/faq.md: 52 added lines, 0 removed lines.
Original line number Diff line number Diff line
# 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.
+1 −0
Changes for docs/index.rst: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -97,6 +97,7 @@ Contents
   usage_and_configuration/index
   integrations/index
   guides/index
   faq

.. toctree::
   :maxdepth: 3