diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst
index 93c65ba7358c9..2dc5ed07544d1 100644
--- a/doc/source/development/contributing.rst
+++ b/doc/source/development/contributing.rst
@@ -635,6 +635,8 @@ many errors as possible, but it may not correct *all* of them. Thus, it is
recommended that you run ``cpplint`` to double check and make any other style
fixes manually.
+.. _contributing.code-formatting:
+
Python (PEP8 / black)
~~~~~~~~~~~~~~~~~~~~~
@@ -656,19 +658,8 @@ apply ``black`` as you edit files.
You should use a ``black`` version >= 19.10b0 as previous versions are not compatible
with the pandas codebase.
-Optionally, you may wish to setup `pre-commit hooks `_
-to automatically run ``black`` and ``flake8`` when you make a git commit. This
-can be done by installing ``pre-commit``::
-
- pip install pre-commit
-
-and then running::
-
- pre-commit install
-
-from the root of the pandas repository. Now ``black`` and ``flake8`` will be run
-each time you commit changes. You can skip these checks with
-``git commit --no-verify``.
+If you wish to run these checks automatically, we encourage you to use
+:ref:`pre-commits ` instead.
One caveat about ``git diff upstream/master -u -- "*.py" | flake8 --diff``: this
command will catch any stylistic errors in your changes specifically, but
@@ -676,7 +667,7 @@ be beware it may not catch all of them. For example, if you delete the only
usage of an imported function, it is stylistically incorrect to import an
unused function. However, style-checking the diff will not catch this because
the actual import is not part of the diff. Thus, for completeness, you should
-run this command, though it will take longer::
+run this command, though it may take longer::
git diff upstream/master --name-only -- "*.py" | xargs -r flake8
@@ -694,6 +685,8 @@ behaviour as follows::
This will get all the files being changed by the PR (and ending with ``.py``),
and run ``flake8`` on them, one after the other.
+Note that these commands can be run analogously with ``black``.
+
.. _contributing.import-formatting:
Import formatting
@@ -716,7 +709,6 @@ A summary of our current import sections ( in order ):
Imports are alphabetically sorted within these sections.
-
As part of :ref:`Continuous Integration ` checks we run::
isort --recursive --check-only pandas
@@ -740,8 +732,37 @@ to automatically format imports correctly. This will modify your local copy of t
The `--recursive` flag can be passed to sort all files in a directory.
+Alternatively, you can run a command similar to what was suggested for ``black`` and ``flake8`` :ref:`right above `::
+
+ git diff upstream/master --name-only -- "*.py" | xargs -r isort
+
+Where similar caveats apply if you are on OSX or Windows.
+
You can then verify the changes look ok, then git :ref:`commit ` and :ref:`push `.
+.. _contributing.pre-commit:
+
+Pre-Commit
+~~~~~~~~~~
+
+You can run many of these styling checks manually as we have described above. However,
+we encourage you to use `pre-commit hooks `_ instead
+to automatically run ``black``, ``flake8``, ``isort`` when you make a git commit. This
+can be done by installing ``pre-commit``::
+
+ pip install pre-commit
+
+and then running::
+
+ pre-commit install
+
+from the root of the pandas repository. Now all of the styling checks will be
+run each time you commit changes without your needing to run each one manually.
+In addition, using this pre-commit hook will also allow you to more easily
+remain up-to-date with our code checks as they change.
+
+Note that if needed, you can skip these checks with ``git commit --no-verify``.
+
Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~