#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/user_guide/features/formatting_code/troubleshooting.rst

@@ -45,6 +45,7 @@ might want to ignore automatically applied formatting.
 |                       |   <line-to-ignore> # noqa: F401|    # ruff: noqa F401  |
 +-----------------------+--------------------------------+-----------------------+
 
+See also :ref:`ignore_ruff_findings`.
 
 In the ``checks.yml``, ``format:check`` wants me to reformat code I did not modify
 ------------------------------------------------------------------------------------

doc/user_guide/features/ignore_ruff_findings.rst

@@ -0,0 +1,15 @@
+.. _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 `Ruff documentation <https://docs.astral.sh/ruff/configuration>`_

doc/user_guide/introduction.rst

@@ -0,0 +1,34 @@
+Introduction
+============
+
+Exasol's Python Toolbox (PTB) helps you creating and maintaining your Python projects.
+
+PTB simplifies keeping all of our 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
+.. _Black: https://black.readthedocs.io
+.. _Ruff: https://docs.astral.sh/ruff
+.. _Pylint: https://pylint.readthedocs.io
+.. _Cookiecutter: https://cookiecutter.readthedocs.io
+.. _Mypy: https://mypy.readthedocs.io
+.. _Coverage: https://coverage.readthedocs.io
+.. _Bandit: https://bandit.readthedocs.io
+.. _Sphinx: https://www.sphinx-doc.org/en/master
+.. _Sonar: https://docs.sonarsource.com/sonarqube-server

doc/user_guide/troubleshooting.rst

@@ -6,4 +6,6 @@ Troubleshooting
 .. toctree::
    :maxdepth: 1
 
+   Formatting issues <features/formatting_code/troubleshooting>
    features/metrics/ignore_findings
+   features/ignore_ruff_findings

doc/user_guide/user_guide.rst

@@ -6,6 +6,7 @@
 .. toctree::
     :maxdepth: 2
 
+    introduction
     dependencies
     getting_started
     configuration