doc/source/hacking: Remove pycodestyle, add Black

Now that code formatting is managed by Black, and we don't need to run
`pycodestyle` separately, remove corresponding mentions from hacking
documentation.

Add documentation on how to run Black.

Move out linting and formatting into a separate section for better
readability.

2 files changed, 26 insertions, 16 deletions

diff --git a/doc/source/hacking/coding_guidelines.rst b/doc/source/hacking/coding_guidelines.rst
index 7088fc365..4ba6360b6 100644
--- a/doc/source/hacking/coding_guidelines.rst
+++ b/doc/source/hacking/coding_guidelines.rst
@@ -19,10 +19,10 @@ Approximate PEP-8 Style
 ~~~~~~~~~~~~~~~~~~~~~~~
 Python coding style for BuildStream is approximately `pep8 <https://www.python.org/dev/peps/pep-0008/>`_.
 
-We have a couple of minor exceptions to this standard, we dont want to compromise
-code readability by being overly restrictive on line length for instance.
+The coding style is automatically enforced by `black <https://black.readthedocs.io/en/stable/>`_.
 
-The pep8 linter will run automatically when :ref:`running the test suite <contributing_testing>`.
+Formatting will be checked automatically when running the testsuite on CI. For
+details on how to format your code locally, see :ref:`formatting code <contributing_formatting_code>`.
 
 
 Line lengths
diff --git a/doc/source/hacking/using_the_testsuite.rst b/doc/source/hacking/using_the_testsuite.rst
index 2bd2696bb..0e476c7de 100644
--- a/doc/source/hacking/using_the_testsuite.rst
+++ b/doc/source/hacking/using_the_testsuite.rst
@@ -54,18 +54,6 @@ the same arguments you would give `tox`::
 
   detox -e lint,py36,py37
 
-Linting is performed separately from testing. In order to run the linting step which
-consists of running the ``pycodestyle`` and ``pylint`` tools, run the following::
-
-  tox -e lint
-
-.. tip::
-
-   The project specific pylint and pycodestyle configurations are stored in the
-   toplevel buildstream directory in the ``.pylintrc`` file and ``setup.cfg`` files
-   respectively. These configurations can be interesting to use with IDEs and
-   other developer tooling.
-
 The output of all failing tests will always be printed in the summary, but
 if you want to observe the stdout and stderr generated by a passing test,
 you can pass the ``-s`` option to pytest as such::
@@ -155,9 +143,31 @@ can run ``tox`` with ``-r`` or  ``--recreate`` option.
    tests::
 
      tox -e venv -- <your command(s) here>
-     
+
    Any commands after ``--`` will be run a virtualenv managed by tox.
 
+Running linters
+~~~~~~~~~~~~~~~
+Linting is performed separately from testing. In order to run the linting step which
+consists of running the ``pylint`` tool, run the following::
+
+  tox -e lint
+
+.. tip::
+
+   The project specific pylint configuration is stored in the toplevel
+   buildstream directory in the ``.pylintrc`` file. This configuration can be
+   interesting to use with IDEs and other developer tooling.
+
+.. _contributing_formatting_code:
+
+Formatting code
+~~~~~~~~~~~~~~~
+Similar to linting, code formatting is also done via a ``tox`` environment. To
+format the code using the ``black`` tool, run the following::
+
+   tox -e format
+
 Observing coverage
 ~~~~~~~~~~~~~~~~~~
 Once you have run the tests using `tox` (or `detox`), some coverage reports will