Add a FAQ entry regarding the isort compatibility issue (#338)

Author: Nicoretti

doc/changes/unreleased.md

@@ -13,6 +13,7 @@
 ## 📚 Documentation
 * Updated design doc (Added known Issues)
 * Updated migration progress table
+* Updated the FAQ with an entry about the ``isort`` compatibility issue
 
 ## 🔧 Changed
 * Updated `actions/upload-artifacts` version to `4.6.0`

doc/faq.rst

@@ -63,3 +63,33 @@ Limited Previous Versions in Multiversion Documentation
 -------------------------------------------------------
 
 If not all previous versions of the project are available via the version selection box of the multiversion documentation, it is likely due to the fact that the unavailable documentation for those versions was not in a compatible format (there hasn't been a compatible setup of a Sphinx-based documentation).
+
+
+.. _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?$"