Clean up from self-review

Author: ArBridgeman

doc/faq.rst

@@ -3,7 +3,6 @@
 :octicon:`question` FAQ
 =======================
 
-
 .. _faq_no_module_noxconfig:
 
 No Module Named 'noxconfig'
@@ -16,5 +15,3 @@ There are several methods to configure your shell:
     1. For a one-time setup: :code:`PYTHONPATH=\`pwd\` nox -s task`
     2. For a general setup: :code:`export PYTHONPATH=`pwd``
     3. Alternatively, tools like `direnv <https://direnv.net>`_ can be used.
-
-.. _faq_failing_format_check:

doc/user_guide/features/formatting_code/index.rst

@@ -1,6 +1,5 @@
 .. _formatting_code:
 
-
 Formatting code
 ===============
 
@@ -9,19 +8,25 @@ Formatting code
 
     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.
+The PTB automatically formats code and ensures via a step in the ``checks.yml`` GitHub
+workflow that committed code adheres to these standards. The goals of this are to
+improve the readability and maintainability of the code and to provide a uniform
+experience across projects.
+
+.. _formatting_sessions:
 
 Nox sessions
 ++++++++++++
 
-For autoformatting, we use the following tools:
+For autoformatting, the following tools are used:
 
-* `black` - automatically formats Python code to maintain consistent styling standards.
-* `isort`
-* `pyupgrade`
+* `black <https://black.readthedocs.io/en/stable/the_black_code_style/index.html>`__ -
+  formats Python code to maintain consistent styling standards.
+* `isort <https://pycqa.github.io/isort/index.html>`__ - organizes and formats Python
+  import statements alphabetically and by type (from __future__, standard library
+  packages, third party packages, and local application imports).
+* `pyupgrade <https://pypi.org/project/pyupgrade/>`__ - upgrades syntax for newer
+  versions of the Python language.
 
 In the PTB, these tools are bundled into nox sessions to ensure that they are run in a
 deterministic manner.
@@ -40,6 +45,8 @@ deterministic manner.
 
 .. _formatting_configuration:
 
+TODO
+
 Configuration
 +++++++++++++
 black
@@ -52,6 +59,9 @@ Your ``black`` configuration should look similar to this:
   :start-at: [tool.black]
   :end-before: [tool.isort]
 
+For further configuration options, see
+`black configuration <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-format>`__.
+
 isort
 ^^^^^
 Ensure ``isort`` is configured with compatibility for ``black``:
@@ -61,6 +71,14 @@ Ensure ``isort`` is configured with compatibility for ``black``:
   :start-at: [tool.isort]
   :end-before: [tool.pylint.master]
 
+For further configuration options, see
+`isort options <https://pycqa.github.io/isort/docs/configuration/options.html>`__.
+
 pyupgrade
 ^^^^^^^^^
 No initial configuration of ``pyupgrade`` is required.
+
+For individual configuration, see the
+`pyupgrade CLI options <https://pypi.org/project/pyupgrade/>`__. These can
+be passed to the :ref:`formatting_sessions` via the ``pyupgrade_args``
+attribute of the :class:`noxconfig.Config`.

doc/user_guide/features/formatting_code/troubleshooting.rst

@@ -1,7 +1,6 @@
 Troubleshooting
 ===============
 
-
 Formatting still fails after running ``project:fix``
 ----------------------------------------------------
 

doc/user_guide/getting_started.rst

@@ -69,7 +69,7 @@ Install all necessary project and development dependencies for the project:
 
 **4. Start using your project**
 
-List all available nox tasks:
+List all available nox sessions:
 
 .. code-block:: shell
 
@@ -115,10 +115,10 @@ For further reference, see the specific configurations for:
 * :ref:`formatting code <formatting_configuration>`
 
 
-4. Make the toolbox tasks available
-+++++++++++++++++++++++++++++++++++
-To use the standard toolbox task via nox, just import them in your ``noxfile.py``.
-If you only need the standard tasks provided by the toolbox, your ``noxfile.py`` is
+4. Make the toolbox sessions available
+++++++++++++++++++++++++++++++++++++++
+To use the standard toolbox session via nox, just import them in your ``noxfile.py``.
+If you only need the standard sessions provided by the toolbox, your ``noxfile.py`` is
 straightforward, and you just can use the example ``noxfile.py`` below.
 
 .. literalinclude:: ../../project-template/{{cookiecutter.repo_name}}/noxfile.py
@@ -127,7 +127,7 @@ straightforward, and you just can use the example ``noxfile.py`` below.
 
 .. attention::
 
-    Keep in mind that the current path may not be included in the :code:`PYTHONPATH`, depending on the operating system you are using. This is explained in more detail in this resource: https://fedoraproject.org/wiki/Changes/PythonSafePath. Thus, it might be necessary to properly set the :code:`PYTHONPATH` before running nox. This is because our nox tasks expect the `noxconfig` module to be located within the python path.
+    Keep in mind that the current path may not be included in the :code:`PYTHONPATH`, depending on the operating system you are using. This is explained in more detail in this resource: https://fedoraproject.org/wiki/Changes/PythonSafePath. Thus, it might be necessary to properly set the :code:`PYTHONPATH` before running nox. This is because our nox sessions expect the `noxconfig` module to be located within the python path.
 
     For additional information on resolving this issue, please :ref:`refer to <faq_no_module_noxconfig>`.
 
@@ -136,7 +136,7 @@ straightforward, and you just can use the example ``noxfile.py`` below.
 
 #. Add a :code:`.pre-commit-config.yaml` file to your project root
 
-    If you want to reuse Nox tasks in the pre-commit hooks, feel free to get some inspiration from the Python toolbox itself:
+    If you want to reuse Nox sessions in the pre-commit hooks, feel free to get some inspiration from the Python toolbox itself:
 
     .. literalinclude:: ../../project-template/{{cookiecutter.repo_name}}/.pre-commit-config.yaml
        :language: yaml
@@ -163,4 +163,4 @@ Look at the configuration of Sonar for a:
 
 8. Go 🥜
 +++++++++++++
-You are ready to use the toolbox. With ``nox -l`` you can list all available tasks.
+You are ready to use the toolbox. With ``nox -l`` you can list all available sessions.

doc/user_guide/migrating.rst

@@ -32,8 +32,6 @@ As a first step, it is generally advisable to introduce `Nox`_ as a task runner
 -----------------------------------
 This can be done incrementally for different checks of your project, such as *project*, *test*, *linting*, *documentation*, and *other* tasks.
 As the tasks can be split into roughly five groups, it likely makes sense to integrate at least one group at a time.
-For more details on the current tasks and groups, refer to: :ref:`toolbox tasks`.
-
 
 Overloading a Task
 __________________