[llvm] 15a1d28 - [docs] Add more details about Python formatting (#66141)

[via llvm-commits]

Author: Joel E. Denny
Date: 2023-09-14T12:00:19-04:00
New Revision: 15a1d288ba9d8cd1bbc5ea38df2c3288d1c86a57

URL: https://github.com/llvm/llvm-project/commit/15a1d288ba9d8cd1bbc5ea38df2c3288d1c86a57
DIFF: https://github.com/llvm/llvm-project/commit/15a1d288ba9d8cd1bbc5ea38df2c3288d1c86a57.diff

LOG: [docs] Add more details about Python formatting (#66141)

Describe the darker utility. Make it clear that black/darker's default
rules should be used. Add some examples.

See ongoing discussion at
<https://discourse.llvm.org/t/rfc-document-and-standardize-python-code-style/68257>.

Added: 
    

Modified: 
    llvm/docs/CodingStandards.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 9d87142b0984fda..ed7faa8b56f2de0 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -113,13 +113,43 @@ section. Python code in the LLVM repository should only use language features
 available in this version of Python.
 
 The Python code within the LLVM repository should adhere to the formatting guidelines
-outlined in `PEP-8 <https://peps.python.org/pep-0008/>`_.
+outlined in `PEP 8 <https://peps.python.org/pep-0008/>`_.
 
-For consistency and to limit churn, code should be automatically formatted with the
-`black <https://github.com/psf/black>`_ utility. Black allows changing the formatting
-rules based on major version. In order to avoid unnecessary churn in the formatting rules
+For consistency and to limit churn, code should be automatically formatted with
+the `black <https://github.com/psf/black>`_ utility, which is PEP 8 compliant.
+Use its default rules. For example, avoid specifying ``--line-length`` even
+though it does not default to 80. The default rules can change between major
+versions of black. In order to avoid unnecessary churn in the formatting rules,
 we currently use black version 23.x in LLVM.
 
+When contributing a patch unrelated to formatting, you should format only the
+Python code that the patch modifies. For this purpose, use the `darker
+<https://pypi.org/project/darker/>`_ utility, which runs default black rules
+over only the modified Python code. Doing so should ensure the patch will pass
+the Python format checks in LLVM's pre-commit CI, which also uses darker. When
+contributing a patch specifically for reformatting Python files, use black,
+which currently only supports formatting entire files.
+
+Here are some quick examples, but see the black and darker documentation for
+details:
+
+.. code-block:: bash
+
+    $ pip install black=='23.*' darker # install black 23.x and darker
+    $ darker test.py                   # format uncommitted changes
+    $ darker -r HEAD^ test.py          # also format changes from last commit
+    $ black test.py                    # format entire file
+
+Instead of individual file names, you can specify directories to
+darker, and it will find the changed files. However, if a directory is
+large, like a clone of the LLVM repository, darker can be painfully
+slow. In that case, you might wish to use git to list changed files.
+For example:
+
+.. code-block:: bash
+
+   $ darker -r HEAD^ $(git 
diff  --name-only HEAD^)
+
 Mechanical Source Issues
 ========================