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,61 @@
+.. _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`
+
+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,63 @@
+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.
+# TODO REFERENCE
+
+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 developer
+might want 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  |
++-----------------------+--------------------------------+-----------------------+
+
+
+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 what's in the project's **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