From 65741e312c62b6dfded6be91c5b176eda2a1c257 Mon Sep 17 00:00:00 2001
From: Gerasimos Chourdakis <chourdak@in.tum.de>
Date: Tue, 8 Aug 2023 15:41:46 +0300
Subject: [PATCH] Document format_precice_config.py (#235)

Related to https://github.com/precice/precice/pull/1501 and https://github.com/precice/precice-pre-commit-hooks/pull/1
---
 pages/docs/dev-docs/dev-tooling.md | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/pages/docs/dev-docs/dev-tooling.md b/pages/docs/dev-docs/dev-tooling.md
index 56133d90dc..dfdab1fe8b 100644
--- a/pages/docs/dev-docs/dev-tooling.md
+++ b/pages/docs/dev-docs/dev-tooling.md
@@ -25,8 +25,6 @@ To keep the code-base consistent, please use `clang-format` version 8.
 Scripts will explicitly use `clang-format-8` to prevent any problems.
 Looking for precompiled binaries? Here is the [official APT repository](http://apt.llvm.org/).
 
-We also use a custom formatting tool for XML files based on python 3 and the lxml package. So make sure to install it e.g. via `pip install --user lxml`.
-
 To format the entire codebase, run our formatting tool:
 
 ```bash
@@ -73,6 +71,24 @@ void formatted_code_again;
 void formatted_code_yet_again;
 ```
 
+## Formatting preCICE configuration files
+
+To format your `precice-config.xml`, you can use the script `format_precice_config.py` which is part of the [preCICE pre-commit hooks](https://github.com/precice/precice-pre-commit-hooks) (without needing to install the pre-commit hooks) and depends on the lxml package (install it with `pip install --user lxml`). To format a file in place:
+
+```bash
+format_precice_config.py precice-config.xml
+```
+
+The script returns 0 on success, 1 on error, and 2 if a file was modified.
+
+You may want to define an alias for convenience:
+
+```bash
+function preciceConfigFormat(){
+  /path/to/format_precice_config.py "${1:-precice-config.xml}"
+}
+```
+
 ## clang-tidy
 
 The tool `clang-tidy` runs static analysis on C and C++ files and reports warnings in clang error format (i.e. editors can parse them).