From a0d0b89adbefa469fde407928cffd21af4077a45 Mon Sep 17 00:00:00 2001
From: Anders Kaseorg <anders@zulip.com>
Date: Fri, 12 Feb 2021 15:21:10 -0800
Subject: [PATCH] docs: Document Black and isort.

Signed-off-by: Anders Kaseorg <anders@zulip.com>
---
 README.md                       |  1 +
 docs/contributing/code-style.md | 18 ++++++++++++++++--
 docs/testing/linters.md         |  8 ++++++++
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1f3703a403..0e8b43401e 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ largest and fastest growing open source group chat project.
 [![CircleCI branch](https://img.shields.io/circleci/project/github/zulip/zulip/master.svg)](https://circleci.com/gh/zulip/zulip/tree/master)
 [![coverage status](https://img.shields.io/codecov/c/github/zulip/zulip/master.svg)](https://codecov.io/gh/zulip/zulip/branch/master)
 [![Mypy coverage](https://img.shields.io/badge/mypy-100%25-green.svg)][mypy-coverage]
+[![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 [![GitHub release](https://img.shields.io/github/release/zulip/zulip.svg)](https://github.com/zulip/zulip/releases/latest)
 [![docs](https://readthedocs.org/projects/zulip/badge/?version=latest)](https://zulip.readthedocs.io/en/latest/)
diff --git a/docs/contributing/code-style.md b/docs/contributing/code-style.md
index e8de6fe3a9..fb2a655f7b 100644
--- a/docs/contributing/code-style.md
+++ b/docs/contributing/code-style.md
@@ -44,8 +44,12 @@ The Vagrant setup process runs this for you.
 
 `lint` runs many lint checks in parallel, including
 
--   JavaScript ([ESLint](https://eslint.org/))
--   Python ([Pyflakes](https://pypi.python.org/pypi/pyflakes))
+-   JavaScript ([ESLint](https://eslint.org/),
+    [Prettier](https://prettier.io/))
+-   Python ([mypy](http://mypy-lang.org/),
+    [Pyflakes](https://pypi.python.org/pypi/pyflakes),
+    [Black](https://github.com/psf/black),
+    [isort](https://pycqa.github.io/isort/))
 -   templates
 -   Puppet configuration
 -   custom checks (e.g. trailing whitespace and spaces-not-tabs)
@@ -304,6 +308,16 @@ type changes in the future.
 
 ### Python
 
+-   Our Python code is formatted with
+    [Black](https://github.com/psf/black) and
+    [isort](https://pycqa.github.io/isort/).  The [linter
+    tool](../testing/linters.md) enforces this by running Black and
+    isort in check mode, or in write mode with `tools/lint
+    --only=black,isort --fix`.  You may find it helpful to [integrate
+    Black](https://black.readthedocs.io/en/stable/editor_integration.html)
+    and
+    [isort](https://pycqa.github.io/isort/#installing-isorts-for-your-preferred-text-editor)
+    with your editor.
 -   Don't put a shebang line on a Python file unless it's meaningful to
     run it as a script. (Some libraries can also be run as scripts, e.g.
     to run a test suite.)
diff --git a/docs/testing/linters.md b/docs/testing/linters.md
index 84646bf871..b596a73e34 100644
--- a/docs/testing/linters.md
+++ b/docs/testing/linters.md
@@ -17,7 +17,9 @@ prevent common coding errors.
 We borrow some open source tools for much of our linting, and the links
 below will direct you to the official documentation for these projects.
 
+- [Black](https://github.com/psf/black)
 - [ESLint](https://eslint.org)
+- [isort](https://pycqa.github.io/isort/)
 - [mypy](http://mypy-lang.org/)
 - [Prettier](https://prettier.io/)
 - [Puppet](https://puppet.com/) (puppet provides its own mechanism for
@@ -100,6 +102,7 @@ Most of our lint checks get performed by `./tools/lint`.  These include the
 following checks:
 
 - Check Python code with pyflakes.
+- Check Python formatting with Black and isort.
 - Check JavaScript and TypeScript code with ESLint.
 - Check CSS, JavaScript, TypeScript, and YAML formatting with Prettier.
 - Check Python code for custom Zulip rules.
@@ -166,6 +169,11 @@ sense (e.g. a link in a comment to an extremely long URL).
 
 #### Python code
 
+Our Python code is formatted using Black (using the options in the
+`[tool.black]` section of `pyproject.toml`) and isort (using the
+options in `.isort.cfg`).  The `lint` script enforces this by running
+Black and isort in check mode, or in write mode with `--fix`.
+
 The bulk of our Python linting gets outsourced to the "pyflakes" tool.  We
 call "pyflakes" in a fairly vanilla fashion, and then we post-process its
 output to exclude certain specific errors that Zulip is comfortable