]> git.madduck.net Git - etc/vim.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Create FAQ documentation (GH-2247)
authorFelix Hildén <felix.hilden@gmail.com>
Tue, 25 May 2021 20:07:05 +0000 (23:07 +0300)
committerGitHub <noreply@github.com>
Tue, 25 May 2021 20:07:05 +0000 (16:07 -0400)
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

CHANGES.md
docs/_static/custom.css
docs/faq.md [new file with mode: 0644]
docs/index.rst

index 34fa1a2092a89827d89296fa9a2dbd9eaa9c8719..22939e38c122d2e5a3e35c8a81fc22f9f8706e39 100644 (file)
@@ -22,6 +22,7 @@
 
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
 
 - Fix typos discovered by codespell (#2228)
 - Fix Vim plugin installation instructions. (#2235)
+- Add new Frequently Asked Questions page (#2247)
 
 ## 21.5b1
 
 
 ## 21.5b1
 
index c06c40a2dfceaf7e58629a5de91b8a364a541d12..eacd69c15a09463d529d9fe1172718bd38da3a32 100644 (file)
@@ -36,3 +36,9 @@ _:-ms-fullscreen,
     -ms-overflow-style: none;
   }
 }
     -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
@@ -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.
index 2b85cddd3c06d87b91250c972ec6a93184c10dbb..53857995ec6ad759eac0b61bcbd545bbe4806e97 100644 (file)
@@ -97,6 +97,7 @@ Contents
    usage_and_configuration/index
    integrations/index
    guides/index
    usage_and_configuration/index
    integrations/index
    guides/index
+   faq
 
 .. toctree::
    :maxdepth: 3
 
 .. toctree::
    :maxdepth: 3