From fb46c3819080f49e9d77bde0531bfbf1654dc324 Mon Sep 17 00:00:00 2001 From: ckunki Date: Fri, 13 Feb 2026 11:15:22 +0100 Subject: [PATCH] #706: Added description how to ignore findings to the User Guide --- doc/changes/unreleased.md | 4 +++ .../formatting_code/troubleshooting.rst | 1 + .../features/ignore_ruff_findings.rst | 15 ++++++++ doc/user_guide/introduction.rst | 34 +++++++++++++++++++ doc/user_guide/troubleshooting.rst | 2 ++ doc/user_guide/user_guide.rst | 1 + 6 files changed, 57 insertions(+) create mode 100644 doc/user_guide/features/ignore_ruff_findings.rst create mode 100644 doc/user_guide/introduction.rst diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 29f939fba..95ca6dfb0 100644 --- a/doc/changes/unreleased.md +++ b/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 diff --git a/doc/user_guide/features/formatting_code/troubleshooting.rst b/doc/user_guide/features/formatting_code/troubleshooting.rst index 97e26207f..71eb64b4b 100644 --- a/doc/user_guide/features/formatting_code/troubleshooting.rst +++ b/doc/user_guide/features/formatting_code/troubleshooting.rst @@ -45,6 +45,7 @@ might want to ignore automatically applied formatting. | | # 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 ------------------------------------------------------------------------------------ diff --git a/doc/user_guide/features/ignore_ruff_findings.rst b/doc/user_guide/features/ignore_ruff_findings.rst new file mode 100644 index 000000000..c111c996d --- /dev/null +++ b/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 `_ diff --git a/doc/user_guide/introduction.rst b/doc/user_guide/introduction.rst new file mode 100644 index 000000000..ece671d3b --- /dev/null +++ b/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 diff --git a/doc/user_guide/troubleshooting.rst b/doc/user_guide/troubleshooting.rst index ba1232fca..d8707b3a7 100644 --- a/doc/user_guide/troubleshooting.rst +++ b/doc/user_guide/troubleshooting.rst @@ -6,4 +6,6 @@ Troubleshooting .. toctree:: :maxdepth: 1 + Formatting issues features/metrics/ignore_findings + features/ignore_ruff_findings diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index 00c8009fa..9fcda4964 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -6,6 +6,7 @@ .. toctree:: :maxdepth: 2 + introduction dependencies getting_started configuration