[buildstream] 06/08: doc/source/hacking: Remove pycodestyle, add Black

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

root pushed a commit to branch frazer/flake8
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit f6aed04e057f20e573844a03d14dba3c7b3942b4
Author: Chandan Singh <cs...@bloomberg.net>
AuthorDate: Mon Nov 11 17:17:05 2019 +0000

    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.
---
 doc/source/hacking/coding_guidelines.rst   |  6 ++---
 doc/source/hacking/using_the_testsuite.rst | 36 +++++++++++++++++++-----------
 2 files changed, 26 insertions(+), 16 deletions(-)

diff --git a/doc/source/hacking/coding_guidelines.rst b/doc/source/hacking/coding_guidelines.rst
index 7088fc3..4ba6360 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 2bd2696..0e476c7 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