From 7b18170d555e761891d481f47f45591cfa684184 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Tue, 18 May 2021 16:45:14 +0300 Subject: [PATCH 1/5] Create FAQ --- docs/faq/index.rst | 8 ++++++++ docs/faq/items/black_api.md | 4 ++++ docs/faq/items/black_safety.md | 8 ++++++++ docs/faq/items/black_style_stability.md | 6 ++++++ docs/faq/items/file_not_formatted.md | 5 +++++ docs/faq/items/flake8_errors.md | 7 +++++++ docs/faq/items/python2_support.md | 6 ++++++ docs/index.rst | 1 + 8 files changed, 45 insertions(+) create mode 100644 docs/faq/index.rst create mode 100644 docs/faq/items/black_api.md create mode 100644 docs/faq/items/black_safety.md create mode 100644 docs/faq/items/black_style_stability.md create mode 100644 docs/faq/items/file_not_formatted.md create mode 100644 docs/faq/items/flake8_errors.md create mode 100644 docs/faq/items/python2_support.md diff --git a/docs/faq/index.rst b/docs/faq/index.rst new file mode 100644 index 00000000000..9c0c01e4710 --- /dev/null +++ b/docs/faq/index.rst @@ -0,0 +1,8 @@ +Frequently Asked Questions +========================== +The most common questions and issues users face are aggregated to this FAQ. + +.. toctree:: + :glob: + + items/* diff --git a/docs/faq/items/black_api.md b/docs/faq/items/black_api.md new file mode 100644 index 00000000000..47a8e452409 --- /dev/null +++ b/docs/faq/items/black_api.md @@ -0,0 +1,4 @@ +# Does Black have an API? + +No. _Black_ is a command line tool. Many [integrations](../../integrations/index.rst) +are provided, but a Python interface is not one of them. diff --git a/docs/faq/items/black_safety.md b/docs/faq/items/black_safety.md new file mode 100644 index 00000000000..7022d4128ae --- /dev/null +++ b/docs/faq/items/black_safety.md @@ -0,0 +1,8 @@ +# 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. diff --git a/docs/faq/items/black_style_stability.md b/docs/faq/items/black_style_stability.md new file mode 100644 index 00000000000..c681f12d26e --- /dev/null +++ b/docs/faq/items/black_style_stability.md @@ -0,0 +1,6 @@ +# How stable is Black's style? + +Quite. _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. diff --git a/docs/faq/items/file_not_formatted.md b/docs/faq/items/file_not_formatted.md new file mode 100644 index 00000000000..cb4945d817f --- /dev/null +++ b/docs/faq/items/file_not_formatted.md @@ -0,0 +1,5 @@ +# 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. diff --git a/docs/faq/items/flake8_errors.md b/docs/faq/items/flake8_errors.md new file mode 100644 index 00000000000..c470ca3b864 --- /dev/null +++ b/docs/faq/items/flake8_errors.md @@ -0,0 +1,7 @@ +# 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). diff --git a/docs/faq/items/python2_support.md b/docs/faq/items/python2_support.md new file mode 100644 index 00000000000..c561fb73f72 --- /dev/null +++ b/docs/faq/items/python2_support.md @@ -0,0 +1,6 @@ +# Does Black support Python 2? + +By default, no. [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_, at +least Python 3.6 is required though. diff --git a/docs/index.rst b/docs/index.rst index 2b85cddd3c0..8c08b3d76cb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -95,6 +95,7 @@ Contents getting_started usage_and_configuration/index + faq/index integrations/index guides/index From cae7b01aebe3c2449b0838048832e8bff429a7dc Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Wed, 19 May 2021 20:41:43 +0300 Subject: [PATCH 2/5] Address feedback --- docs/faq/items/black_api.md | 6 ++++-- docs/faq/items/python2_support.md | 6 +++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/faq/items/black_api.md b/docs/faq/items/black_api.md index 47a8e452409..6272b776d0a 100644 --- a/docs/faq/items/black_api.md +++ b/docs/faq/items/black_api.md @@ -1,4 +1,6 @@ # Does Black have an API? -No. _Black_ is a command line tool. Many [integrations](../../integrations/index.rst) -are provided, but a Python interface is not one of them. +Not currently. _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. diff --git a/docs/faq/items/python2_support.md b/docs/faq/items/python2_support.md index c561fb73f72..2f0fcc131c0 100644 --- a/docs/faq/items/python2_support.md +++ b/docs/faq/items/python2_support.md @@ -1,6 +1,6 @@ # Does Black support Python 2? -By default, no. [Install](../../getting_started.md#installation) with the `python2` +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_, at -least Python 3.6 is required though. +likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though, +Python 3.6 or newer is required. From db9b5bfa917ca970e0db8338b68b9ab7b272aba5 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Sun, 23 May 2021 20:48:21 +0300 Subject: [PATCH 3/5] Move to single markdown file --- docs/_static/custom.css | 6 +++ docs/faq.md | 52 +++++++++++++++++++++++++ docs/faq/index.rst | 8 ---- docs/faq/items/black_api.md | 6 --- docs/faq/items/black_safety.md | 8 ---- docs/faq/items/black_style_stability.md | 6 --- docs/faq/items/file_not_formatted.md | 5 --- docs/faq/items/flake8_errors.md | 7 ---- docs/faq/items/python2_support.md | 6 --- docs/index.rst | 2 +- 10 files changed, 59 insertions(+), 47 deletions(-) create mode 100644 docs/faq.md delete mode 100644 docs/faq/index.rst delete mode 100644 docs/faq/items/black_api.md delete mode 100644 docs/faq/items/black_safety.md delete mode 100644 docs/faq/items/black_style_stability.md delete mode 100644 docs/faq/items/file_not_formatted.md delete mode 100644 docs/faq/items/flake8_errors.md delete mode 100644 docs/faq/items/python2_support.md diff --git a/docs/_static/custom.css b/docs/_static/custom.css index c06c40a2dfc..eacd69c15a0 100644 --- 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 index 00000000000..95a8220e585 --- /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 currently. _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. _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/faq/index.rst b/docs/faq/index.rst deleted file mode 100644 index 9c0c01e4710..00000000000 --- a/docs/faq/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Frequently Asked Questions -========================== -The most common questions and issues users face are aggregated to this FAQ. - -.. toctree:: - :glob: - - items/* diff --git a/docs/faq/items/black_api.md b/docs/faq/items/black_api.md deleted file mode 100644 index 6272b776d0a..00000000000 --- a/docs/faq/items/black_api.md +++ /dev/null @@ -1,6 +0,0 @@ -# Does Black have an API? - -Not currently. _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. diff --git a/docs/faq/items/black_safety.md b/docs/faq/items/black_safety.md deleted file mode 100644 index 7022d4128ae..00000000000 --- a/docs/faq/items/black_safety.md +++ /dev/null @@ -1,8 +0,0 @@ -# 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. diff --git a/docs/faq/items/black_style_stability.md b/docs/faq/items/black_style_stability.md deleted file mode 100644 index c681f12d26e..00000000000 --- a/docs/faq/items/black_style_stability.md +++ /dev/null @@ -1,6 +0,0 @@ -# How stable is Black's style? - -Quite. _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. diff --git a/docs/faq/items/file_not_formatted.md b/docs/faq/items/file_not_formatted.md deleted file mode 100644 index cb4945d817f..00000000000 --- a/docs/faq/items/file_not_formatted.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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. diff --git a/docs/faq/items/flake8_errors.md b/docs/faq/items/flake8_errors.md deleted file mode 100644 index c470ca3b864..00000000000 --- a/docs/faq/items/flake8_errors.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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). diff --git a/docs/faq/items/python2_support.md b/docs/faq/items/python2_support.md deleted file mode 100644 index 2f0fcc131c0..00000000000 --- a/docs/faq/items/python2_support.md +++ /dev/null @@ -1,6 +0,0 @@ -# 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 8c08b3d76cb..53857995ec6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -95,9 +95,9 @@ Contents getting_started usage_and_configuration/index - faq/index integrations/index guides/index + faq .. toctree:: :maxdepth: 3 From a19e162ea8ee8da31cea5c6371ed99d8a2f95cc3 Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Sun, 23 May 2021 20:54:25 +0300 Subject: [PATCH 4/5] Minor wording improvements --- docs/faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 95a8220e585..46e459883ed 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -9,7 +9,7 @@ The most common questions and issues users face are aggregated to this FAQ. ## Does Black have an API? -Not currently. _Black_ is fundamentally a command line tool. Many +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. @@ -25,7 +25,7 @@ is raised and the file is left untouched. ## How stable is Black's style? -Quite. _Black_ aims to enforce one style and one style only, with some room for +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. From 87ceef436e5da12c1eca527b2a86a01417230f3e Mon Sep 17 00:00:00 2001 From: felix-hilden Date: Mon, 24 May 2021 00:03:18 +0300 Subject: [PATCH 5/5] Add changelog entry --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index 603554cd8b7..09f613c1e3d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -17,6 +17,7 @@ - Fix typos discovered by codespell (#2228) - Fix Vim plugin installation instructions. (#2235) +- Add new Frequently Asked Questions page (#2247) ## 21.5b1