From 28604ab03df92fa9636933a11c1cbf30f3111eed Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Mon, 24 Jun 2019 17:48:05 +0100
Subject: [PATCH] Add info about black to code_style.rst (#5537)

Fixes #5533

Adds information about how to install and run black on the codebase.
---
 changelog.d/5537.misc |  1 +
 docs/code_style.rst   | 95 +++++++++++++++++++++----------------------
 2 files changed, 47 insertions(+), 49 deletions(-)
 create mode 100644 changelog.d/5537.misc

diff --git a/changelog.d/5537.misc b/changelog.d/5537.misc
new file mode 100644
index 0000000000..870a5ff18b
--- /dev/null
+++ b/changelog.d/5537.misc
@@ -0,0 +1 @@
+Add information about how to install and run `black` on the codebase to code_style.rst.
diff --git a/docs/code_style.rst b/docs/code_style.rst
index 62800b5b3e..e3ca626bfd 100644
--- a/docs/code_style.rst
+++ b/docs/code_style.rst
@@ -1,43 +1,60 @@
-- Everything should comply with PEP8. Code should pass
-  ``pep8 --max-line-length=100`` without any warnings.
+# Code Style
 
-- **Indenting**:
+The Synapse codebase uses a number of code formatting tools in order to
+quickly and automatically check for formatting (and sometimes logical) errors
+in code.
 
-  - NEVER tabs. 4 spaces to indent.
+The necessary tools are detailed below.
 
-  - follow PEP8; either hanging indent or multiline-visual indent depending
-    on the size and shape of the arguments and what makes more sense to the
-    author. In other words, both this::
+## Formatting tools
 
-      print("I am a fish %s" % "moo")
+The Synapse codebase uses [black](https://pypi.org/project/black/) as an
+opinionated code formatter, ensuring all comitted code is properly
+formatted.
 
-    and this::
+First install ``black`` with::
 
-      print("I am a fish %s" %
-            "moo")
+  pip install --upgrade black
 
-    and this::
+Have ``black`` auto-format your code (it shouldn't change any
+functionality) with::
 
-        print(
-            "I am a fish %s" %
-            "moo",
-        )
+  black . --exclude="\.tox|build|env"
 
-    ...are valid, although given each one takes up 2x more vertical space than
-    the previous, it's up to the author's discretion as to which layout makes
-    most sense for their function invocation.  (e.g. if they want to add
-    comments per-argument, or put expressions in the arguments, or group
-    related arguments together, or want to deliberately extend or preserve
-    vertical/horizontal space)
+- **flake8**
 
-- **Line length**:
+  ``flake8`` is a code checking tool. We require code to pass ``flake8`` before being merged into the codebase.
 
-  Max line length is 79 chars (with flexibility to overflow by a "few chars" if
-  the overflowing content is not semantically significant and avoids an
-  explosion of vertical whitespace).
+  Install ``flake8`` with::
 
-  Use parentheses instead of ``\`` for line continuation where ever possible
-  (which is pretty much everywhere).
+    pip install --upgrade flake8
+
+  Check all application and test code with::
+
+    flake8 synapse tests
+
+- **isort**
+
+  ``isort`` ensures imports are nicely formatted, and can suggest and
+  auto-fix issues such as double-importing.
+
+  Install ``isort`` with::
+
+    pip install --upgrade isort
+
+  Auto-fix imports with::
+
+    isort -rc synapse tests
+
+  ``-rc`` means to recursively search the given directories.
+
+It's worth noting that modern IDEs and text editors can run these tools
+automatically on save. It may be worth looking into whether this
+functionality is supported in your editor for a more convenient development
+workflow. It is not, however, recommended to run ``flake8`` on save as it
+takes a while and is very resource intensive.
+
+## General rules
 
 - **Naming**:
 
@@ -46,26 +63,6 @@
 
 - Use double quotes ``"foo"`` rather than single quotes ``'foo'``.
 
-- **Blank lines**:
-
-  - There should be max a single new line between:
-
-    - statements
-    - functions in a class
-
-  - There should be two new lines between:
-
-    - definitions in a module (e.g., between different classes)
-
-- **Whitespace**:
-
-  There should be spaces where spaces should be and not where there shouldn't
-  be:
-
-  - a single space after a comma
-  - a single space before and after for '=' when used as assignment
-  - no spaces before and after for '=' for default values and keyword arguments.
-
 - **Comments**: should follow the `google code style
   <http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments>`_.
   This is so that we can generate documentation with `sphinx
@@ -76,7 +73,7 @@
 
 - **Imports**:
 
-  - Prefer to import classes and functions than packages or modules.
+  - Prefer to import classes and functions rather than packages or modules.
 
     Example::