#706: Added description how to ignore findings to the User Guide

doc/changes/unreleased.md

@@ -6,6 +6,10 @@
 
 * #691: Started customization of PTB workflows by defining the YML schema
 
+## Documentation
+
+* #706: Added description how to ignore findings to the User Guide
+
 ## Refactoring
 
 * #664: Removed deprecation warning for projects to switch over to BaseConfig

doc/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "Exasol Toolbox"
-copyright = "2022, Exasol"  # pylint: disable=redefined-builtin
+copyright = "2026, Exasol"  # pylint: disable=redefined-builtin
 author = "Exasol"
 
 # -- General configuration ---------------------------------------------------

doc/user_guide/features/formatting_code/index.rst

@@ -4,7 +4,7 @@ Formatting code
 ===============
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     configuration
     troubleshooting

doc/user_guide/features/formatting_code/troubleshooting.rst

@@ -3,68 +3,9 @@
 Troubleshooting
 ===============
 
-Formatting still fails after running ``format:fix``
-----------------------------------------------------
+.. toctree::
+    :maxdepth: 2
 
-If when you execute:
-
-#. Run ``format:fix``
-#. Run ``format:check``
-
-you receive an error from ``format:check`` (i.e. ``isort`` or ``black``), it it
-likely that you need to update your configuration to align with
-:ref:`formatting_configuration`.
-
-.. _prevent_auto_format:
-
-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  |
-+-----------------------+--------------------------------+-----------------------+
-| formatting from ruff  | .. code-block:: python         | .. code-block:: python|
-| (example with F401)   |                                |                       |
-|                       |   <line-to-ignore> # noqa: F401|    # ruff: noqa F401  |
-+-----------------------+--------------------------------+-----------------------+
-
-
-In the ``checks.yml``, ``format:check`` 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.
+    ../../troubleshooting/format_check_errors_due_to_configuration_issues
+    ../../troubleshooting/format_check_reports_unmodified_files
+    ../../troubleshooting/formatting_disable

doc/user_guide/getting_started.rst

@@ -15,7 +15,8 @@ Creating a New Project with Exasol-Toolbox Support
 
 .. important::
 
-    To establish a new project with toolbox support, you need to have `Cookiecutter <https://www.cookiecutter.io>`_ installed:
+    To establish a new project with toolbox support, you need to have
+    `Cookiecutter <https://www.cookiecutter.io>`_ installed:
 
     :code:`pip install cookiecutter`
 
@@ -80,6 +81,8 @@ List all available nox sessions:
 Integrating Exasol-Toolbox into your Project
 --------------------------------------------
 
+See also :ref:`migrating_legacy_projects`.
+
 1. Add the toolbox as a dependency
 ++++++++++++++++++++++++++++++++++
 

doc/user_guide/migrating.rst

@@ -1,3 +1,5 @@
+.. _migrating_legacy_projects:
+
 Migrating Legacy Projects
 =========================
 

doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst

@@ -0,0 +1,11 @@
+Format Check Errors Due to Configuration Issues
+===============================================
+
+When you execute:
+
+#. Run ``format:fix``
+#. Run ``format:check``
+
+and you receive an error (i.e. ``isort`` or ``black``), it is likely that you
+need to update your configuration to align with
+:ref:`formatting_configuration`.

doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst

@@ -0,0 +1,27 @@
+.. _format_check_reports_unmodified_files:
+
+Format Check Reports Unmodified Files
+=====================================
+
+Sometimes ``checks.yml`` or ``format:check`` report formatting issues in
+files that have not been modified.
+
+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/troubleshooting/formatting_disable.rst

@@ -0,0 +1,34 @@
+.. _prevent_auto_format:
+
+Prevent Auto Format
+===================
+
+Sometimes you need to disable auto format in specific places.
+
+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  |
++-----------------------+--------------------------------+-----------------------+
+| formatting from ruff  | .. code-block:: python         | .. code-block:: python|
+| (example with F401)   |                                |                       |
+|                       |   <line-to-ignore> # noqa: F401|    # ruff: noqa F401  |
++-----------------------+--------------------------------+-----------------------+
+
+See also :ref:`ignore_ruff_findings`.

doc/user_guide/troubleshooting/ignore_ruff_findings.rst

@@ -0,0 +1,18 @@
+.. _ignore_ruff_findings:
+
+Ignoring Ruff Findings
+======================
+
+A typical example is when importing all PTB's Nox sessions in your
+``noxfile.py``, which may cause ruff to report error "F403 unused import".
+
+You can ignore this finding by appending a comment to the code line:
+
+.. code-block:: python
+
+    from exasol.toolbox.nox.tasks import *  # noqa: F403
+
+See also
+
+* `Ruff documentation <https://docs.astral.sh/ruff/configuration>`_
+* :ref:`prevent_auto_format`

doc/user_guide/troubleshooting/index.rst

@@ -0,0 +1,20 @@
+.. _ptb_troubleshooting:
+
+Troubleshooting
+===============
+
+This page helps you in case some of the :ref:`tools employed by the PTB
+<user_guide>` do not exactly do what you want or might report errors you want
+to ignore for sound reasons.
+
+Here is a list of problems and error messages you might encounter along with
+proposed mitigations, some potentially specific to the related tool.
+
+.. toctree::
+   :maxdepth: 1
+
+   format_check_errors_due_to_configuration_issues
+   format_check_reports_unmodified_files
+   formatting_disable
+   "F403 unused import" (reported by Ruff) <ignore_ruff_findings>
+   Sonar findings <../features/metrics/ignore_findings>

doc/user_guide/user_guide.rst

@@ -5,11 +5,44 @@
 
 .. toctree::
     :maxdepth: 2
+    :hidden:
 
     dependencies
     getting_started
     configuration
     features/index
-    troubleshooting
+    troubleshooting/index
     customization
     migrating
+
+Exasol's Python Toolbox (PTB) helps you creating and maintaining your Python projects.
+
+PTB simplifies keeping all of your projects up-to-date, secure, without bugs, using uniform code style and formatting, correctly typed, decent quality wrt. static code analysis, nicely documented, and equipped with a unified CI/CD pipeline for building, testing, and publishing their artifacts.
+
+The PTB gains its name from employing a series of well-established tools to satisfy these goals:
+
+* `Poetry`_ for packaging and managing dependencies
+* `Nox`_ for using the tools via a common CLI
+* `Black`_ and `Ruff`_ for source code formatting
+* `Pylint`_ / `Ruff` for linting
+* `Cookiecutter`_ for setting up new projects from a uniform template
+* `Mypy`_ for static type checking
+* `Coverage`_ for measuring code coverage by tests
+* `Bandit`_ for detecting security vulnerabilities
+* `Sphinx`_ for generating the documentation
+* `Sonar`_ for reporting code quality based on the findings by other tools
+
+In rare cases you may need to disable a particular finding reported by one of
+these tools, see :ref:`ptb_troubleshooting`.
+
+.. _Poetry: https://python-poetry.org
+.. _Nox: https://nox.thea.codes/en/stable/
+.. _Black: https://black.readthedocs.io/en/stable/
+.. _Ruff: https://docs.astral.sh/ruff
+.. _Pylint: https://pylint.readthedocs.io/en/stable/
+.. _Cookiecutter: https://cookiecutter.readthedocs.io/en/stable/
+.. _Mypy: https://mypy.readthedocs.io/en/stable/
+.. _Coverage: https://coverage.readthedocs.io/en/7.13.4/
+.. _Bandit: https://bandit.readthedocs.io/en/latest/
+.. _Sphinx: https://www.sphinx-doc.org/en/master
+.. _Sonar: https://docs.sonarsource.com/sonarqube-server