Add documentation about formatting

Author: ArBridgeman

doc/faq.rst

@@ -18,30 +18,3 @@ There are several methods to configure your shell:
     3. Alternatively, tools like `direnv <https://direnv.net>`_ can be used.
 
 .. _faq_failing_format_check:
-
-Format Still Fails After Running ``project:fix``
-------------------------------------------------
-
-If running the following sequence of commands results in ``project:format`` failing with an error during the execution of ``isort``:
-
-#. Run ``project:fix``
-#. Run ``project:format``
-
-It is very likely that you did not configure ``isort`` and/or ``black`` appropriately in your ``pyproject.toml`` file.
-
-Ensure ``isort`` is configured with compatibility for ``black``:
-
-.. code-block:: toml
-
-    [tool.isort]
-    profile = "black"
-    force_grid_wrap = 2
-
-Additionally, your black configuration should look similar to this:
-
-.. code-block:: toml
-
-    [tool.black]
-    line-length = 88
-    verbose = false
-    include = "\\.pyi?$"

doc/user_guide/features/formatting_code/index.rst

@@ -0,0 +1,65 @@
+.. _formatting_code:
+
+
+Formatting code
+===============
+
+.. toctree::
+    :maxdepth: 2
+
+    troubleshooting
+
+The PTB allows you to automatically format your code and to ensure via a step in the
+``checks.yml`` GitHub workflow that your committed code adheres to these standards. The
+goals of this are to improve the readability and maintainability of your code and to
+provide a uniform experience across projects.
+
+Nox sessions
+++++++++++++
+
+For autoformatting, we use the following tools:
+
+* `black` - automatically formats Python code to maintain consistent styling standards.
+* `isort`
+* `pyupgrade`
+* `ruff` - includes a plethora of tools to automatically format code. In
+  the PTB, only the following checks are active:
+
+   * `unused-import (F401) <https://docs.astral.sh/ruff/rules/unused-import/>`__ - remove unused imports
+
+In the PTB, these tools are bundled into nox sessions to ensure that they are run in a
+deterministic manner.
+
++--------------------+------------------+------------------------------------+
+| Nox session        | CI Usage         | Action                             |
++====================+==================+====================================+
+| ``project:fix``    | No               | Applies code formatting changes    |
++--------------------+------------------+------------------------------------+
+| ``project:format`` | ``checks.yml``   | Checks that current code does not  |
+|                    |                  | need to be re-formatted            |
++--------------------+------------------+------------------------------------+
+
+`pre-commit`
+++++++++++++
+
+
+Configuration
++++++++++++++
+
+
+Ensure ``isort`` is configured with compatibility for ``black``:
+
+.. code-block:: toml
+
+    [tool.isort]
+    profile = "black"
+    force_grid_wrap = 2
+
+Additionally, your black configuration should look similar to this:
+
+.. code-block:: toml
+
+    [tool.black]
+    line-length = 88
+    verbose = false
+    include = "\\.pyi?$"

doc/user_guide/features/formatting_code/troubleshooting.rst

@@ -0,0 +1,66 @@
+Troubleshooting
+===============
+
+
+Formatting still fails after running ``project:fix``
+----------------------------------------------------
+
+If when you execute:
+
+#. Run ``project:fix``
+#. Run ``project:format``
+
+you receive an error from ``project:format`` (i.e. ``isort`` or ``black``), it it
+likely that you need to update your configuration to align with :ref:formatting_code.
+
+The automatic formatting is doing x, but we shouldn't do that because of y
+---------------------------------------------------------------------------
+Usually, automatic formatting is helpful, but there are rare cases where a develop might
+in specific areas to ignore automatically applied formatting.
+
+.. note::
+ To ensure that automatic formatting remains useful, developers should always seek
+ to use the minimum fix reasonable for the affected code. In most cases, this would
+ mean adding a comment for a single line.
+
++-----------------------+--------------------------------+-----------------------+
+| Undesired Action      | Single line                    | Within a file         |
++=======================+================================+=======================+
+| formatting from black | .. code-block:: python                                 |
+|                       |                                                        |
+|                       |   # fmt: off                                           |
+|                       |   <code being ignored by black>                        |
+|                       |   # fmt: on                                            |
++-----------------------+--------------------------------+-----------------------+
+| formatting from isort | .. code-block:: python         | .. code-block:: python|
+|                       |                                |                       |
+|                       |   <line-to-ignore> # isort:skip|    # isort:skip_file  |
++-----------------------+--------------------------------+-----------------------+
+| remove unused imports | .. code-block:: python         | .. code-block:: python|
+|                       |                                |                       |
+|                       |   <line-to-ignore> # noqa: F401|    # ruff: noqa F401  |
++-----------------------+--------------------------------+-----------------------+
+
+
+In the ``checks.yml``, ``project:format`` wants me to reformat code I did not modify
+------------------------------------------------------------------------------------
+
+This is likely due to one of our tools (i.e. `black`) being upgraded. Within the
+`pyproject.toml` of the PTB, dependencies are specified to allow
+compatible versions or a restricted version range (i.e., `^6.0.1`, `>=24.1.0,<26.0.0`).
+Such specifications should restrict major reformatting changes to coincide only with a
+new major version of the PTB. However, sometimes a tool's versioning may not properly
+adhere to semantic versioning.
+
+If you encounter this scenario, please:
+
+#. Ensure that your `pyproject.toml` has the PTB restricted to compatible versions
+   (i.e., `^1.7.0`).
+#. Identify which tool is trying to reformat files that you did not modify.
+#. Reset your `poetry.lock` to align with your **default branch**.
+#. More selectively update your `poetry.lock` with `poetry update <package-name>`.
+#. Share with your team which tool & version led to the unexpected changes. So that other
+   PTB users do not experience the same difficulties, we will update the PTB with a patch
+   version to avoid this tool's version and later do a major release to better indicate the
+   breaking changes. You could later create an issue in your GitHub repository to update to
+   the new major version of the PTB & do the reformatting.

doc/user_guide/features/index.rst

@@ -9,6 +9,7 @@ Features
     metrics/collecting_metrics
     creating_a_release
     documentation/index
+    formatting_code/index
     managing_dependencies
 
 Uniform Project Layout

exasol/toolbox/nox/_format.py

@@ -47,6 +47,6 @@ def fix(session: Session) -> None:
 
 @nox.session(name="project:format", python=False)
 def fmt_check(session: Session) -> None:
-    """Checks the project for correct formatting"""
+    """Checks the project for correct formatting_code"""
     py_files = python_files(PROJECT_CONFIG.root)
     _code_format(session=session, mode=Mode.Check, files=py_files)