Document black code formatting

Author: patrick96

docs/IDE.md

@@ -33,7 +33,7 @@ Recommended _Format on Save_ configuration (**IntelliJ IDEA > Preferences > Tool
 2. Check "Optimize imports" (Files:Java)
 3. Check "Run code cleanup". This removes unused imports.
 
-##### Making IntelliJ Feel Similar to Eclipse (Optional)
+#### Making IntelliJ Feel Similar to Eclipse (Optional)
 
 Set IntelliJ to use the Eclipse compiler by going to *IntelliJ IDEA > Preferences > Build, Execution, Deployment > Java Compiler*
 To make IntelliJ work the same way as Eclipse with respect to Problems View and recompilation you need to:
@@ -42,6 +42,31 @@ To make IntelliJ work the same way as Eclipse with respect to Problems View and
 2. Open the problems view:  View > Tool Windows > Problems
 3. Navigate the problems with Cmd ⌥ ↑ and Cmd ⌥ ↓
 
+#### Mx Development
+
+Developing mx itself can also be done using IntelliJ with the python plugin (or PyCharm) and `mx intellijinit` (in the
+mx repository or any other mx suite) as described above is sufficient to add projects for the mx sources.
+
+The main source code is generated as an IntelliJ project named `mx`. In the *Project* view, it will appear
+as `src [mx]` (similarly there is the `mx_tests` project that appears as `tests [mx_tests]`).
+
+##### Formatting
+
+Since 2023.2, IntelliJ with the python plugin (and PyCharm) have built-in support for the *Black* formatter.
+It can be enabled under `Settings > Tools > Black` and it is recommended to turn on both `On code reformat`
+and `On save`.
+In the same setting window, a `black` executable with the correct version should be configured, see
+the [Style Guide](./Styleguide.md) for more information.
+
+By default, this will produce a notification popup everytime *Black* fails to format a file, including when the file is
+ignored by the formatter.
+This can become annoying and can be turned off under:
+
+```
+Settings > Appearance & Behavior > Notifications > Black > Popup type: No popup
+```
+
+As of 2023.2, there is no way to separately configure the different popup severities (error vs. informational).
 
 ### Eclipse
 This section describes how to set up Eclipse for development. For convenience, `$GRAAL` denotes your local repository.

docs/Styleguide.md

@@ -9,6 +9,20 @@ but new code submitted to `mx` should nevertheless follow the guidelines.
 
 ## Python
 
+### Code Style
+
+Code is formatted using [*Black*](https://github.com/psf/black).
+Formatting can be done manually using `mx pyformat`; this will format all eligible python files in this repository.
+It is recommended to set up auto-formatting in your [IDE](./IDE.md) to avoid formatting-only commits.
+
+Only new python files are formatted; which files are excluded is specified in [`pyproject.toml`](../pyproject.toml)
+under `force-exclude`.
+
+To ensure a consistent style, the major version of *Black* is fixed in [`pyproject.toml`](../pyproject.toml).
+Other major versions (newer or older) cannot be used as they could lead to slightly different formatting, failing the
+code format check in the CI.
+See also [*Black*'s Stability Policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
+
 ### Doc comments
 
 Doc comments for modules, classes and methods should use the

mx.mx/mx_mx.py

@@ -41,7 +41,7 @@ def find_black() -> str | None:
 @mx.command(suite.name, "pyformat")
 @mx.no_suite_loading
 def pyformat(arg_list: [str]):
-    parser = argparse.ArgumentParser(prog="mx pyformat", description="TODO document")
+    parser = argparse.ArgumentParser(prog="mx pyformat", description="Format python code using the black formatter")
     parser.add_argument(
         "-n",
         "--dry-run",

pyproject.toml

@@ -9,4 +9,5 @@ target-version = ["py38", "py39", "py310", "py311", "py312"]
 # The original python files
 # Formatting those would lead to large diffs and break git history
 # In addition, formatting for some of these files takes too long to be practical
+# force-exclude is necessary because it prevents formatting even when explicitly requested (e.g. through IDE auto-formatting).
 force-exclude = '(select_jdk)|(remove_jdks.py)|(src/mx/_impl/(mx|mx_[^/]*|select_jdk).py)|(mx.mx/suite.py)'