Formalise style preference description (#2818)

Closes #1256: I reworded our style docs to be more explicit about the style we're aiming for and how it is changed (or isn't).

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 5be7ba6dbdbdccb4880251424c3a6cae3eb7ed9c..0bf5894abdd6202d9298738f79d00c1b26e689d3 100644 (file)
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -2,10 +2,14 @@
 
 ## Code style
 
-_Black_ reformats entire files in place. Style configuration options are deliberately
-limited and rarely added. It doesn't take previous formatting into account, except for
-the magic trailing comma and preserving newlines. It doesn't reformat blocks that start
-with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
+_Black_ aims for consistency, generality, readability and reducing git diffs. Similar
+language constructs are formatted with similar rules. Style configuration options are
+deliberately limited and rarely added. Previous formatting is taken into account as
+little as possible, with rare exceptions like the magic trailing comma. The coding style
+used by _Black_ can be viewed as a strict subset of PEP 8.
+
+_Black_ reformats entire files in place. It doesn't reformat blocks that start with
+`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
 `# fmt: on/off` have to be on the same level of indentation. It also recognizes
 [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
 courtesy for straddling code.
@@ -18,8 +22,7 @@ running `black --preview`.
 
 _Black_ ignores previous formatting and applies uniform horizontal and vertical
 whitespace to your code. The rules for horizontal whitespace can be summarized as: do
-whatever makes `pycodestyle` happy. The coding style used by _Black_ can be viewed as a
-strict subset of PEP 8.
+whatever makes `pycodestyle` happy.
 
 As for vertical whitespace, _Black_ tries to render one full expression or simple
 statement per line. If this fits the allotted line length, great.

diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst
index 3952a17422388f4cd83b2e421658e6438d12c337..511a6ecf0998cc2427d88f57afdfcf3f5d69da88 100644 (file)
--- a/docs/the_black_code_style/index.rst
+++ b/docs/the_black_code_style/index.rst
@@ -12,6 +12,10 @@ The Black Code Style
 While keeping the style unchanged throughout releases has always been a goal,
 the *Black* code style isn't set in stone. It evolves to accommodate for new features
 in the Python language and, occasionally, in response to user feedback.
+Large-scale style preferences presented in :doc:`current_style` are very unlikely to
+change, but minor style aspects and details might change according to the stability
+policy presented below. Ongoing style considerations are tracked on GitHub with the
+`design <https://github.com/psf/black/labels/T%3A%20design>`_ issue label.
 
 Stability Policy
 ----------------