Explicitly reject black autoformatting.

anntzer · anntzer · commit 64f5434f93d5 · 2021-05-17T11:29:10.000+02:00
... or rather, add a mention in the docs so that we can link to it when
reviewing PRs.

Given that the section about pyflakes got removed, also remove the
remaining mention about coverage in that list (in fact, it should be
pytest-cov instead; that part really belongs in testing.rst anyways; and
we don't really enforce the "at least 70% rule"...).
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -160,19 +160,31 @@ rules before submitting a pull request:
   appropriate. Use the `numpy docstring standard
   <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
 
-* Formatting should follow the recommendations of `PEP8
-  <https://www.python.org/dev/peps/pep-0008/>`__. You should consider
-  installing/enabling automatic PEP8 checking in your editor.  Part of the test
-  suite is checking PEP8 compliance, things go smoother if the code is mostly
-  PEP8 compliant to begin with.
+* Formatting should follow the recommendations of PEP8_, as enforced by
+  flake8_.  You can check flake8 compliance from the command line with ::
+
+    python -m pip install flake8
+    flake8 /path/to/module.py
+
+  or your editor may provide integration with it.  Note that Matplotlib
+  intentionally does not use the black_ auto-formatter (1__), in particular due
+  to its unability to understand the semantics of mathematical expressions
+  (2__, 3__).
+
+  .. _PEP8: https://www.python.org/dev/peps/pep-0008/
+  .. _flake8: https://flake8.pycqa.org/
+  .. _black: https://black.readthedocs.io/
+  .. __: https://github.com/matplotlib/matplotlib/issues/18796
+  .. __: https://github.com/psf/black/issues/148
+  .. __: https://github.com/psf/black/issues/1984
 
 * Each high-level plotting function should have a simple example in the
   ``Example`` section of the docstring.  This should be as simple as possible
   to demonstrate the method.  More complex examples should go in the
   ``examples`` tree.
 
-* Changes (both new features and bugfixes) should be tested. See :ref:`testing`
-  for more details.
+* Changes (both new features and bugfixes) should have good test coverage. See
+  :ref:`testing` for more details.
 
 * Import the following modules using the standard scipy conventions::
 
@@ -201,19 +213,6 @@ rules before submitting a pull request:
 * See below for additional points about :ref:`keyword-argument-processing`, if
   applicable for your pull request.
 
-In addition, you can check for common programming errors with the following
-tools:
-
-* Code with a good unittest coverage (at least 70%, better 100%), check with::
-
-   python -m pip install coverage
-   python -m pytest --cov=matplotlib --showlocals -v
-
-* No pyflakes warnings, check with::
-
-   python -m pip install pyflakes
-   pyflakes path/to/module.py
-
 .. note::
 
     The current state of the Matplotlib code base is not compliant with all
