From fb46c3819080f49e9d77bde0531bfbf1654dc324 Mon Sep 17 00:00:00 2001 From: ckunki Date: Fri, 13 Feb 2026 11:15:22 +0100 Subject: [PATCH 1/6] #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 From 1e81a02c34c0370f3cc7c8c085223209f82091a3 Mon Sep 17 00:00:00 2001 From: ckunki Date: Sun, 15 Feb 2026 14:44:40 +0100 Subject: [PATCH 2/6] Added corss references Update year in footer moved introduction to user guide --- doc/conf.py | 2 +- .../features/ignore_ruff_findings.rst | 5 ++- doc/user_guide/getting_started.rst | 5 ++- doc/user_guide/introduction.rst | 34 ------------------ doc/user_guide/migrating.rst | 2 ++ doc/user_guide/troubleshooting.rst | 9 +++-- doc/user_guide/user_guide.rst | 35 ++++++++++++++++++- 7 files changed, 52 insertions(+), 40 deletions(-) delete mode 100644 doc/user_guide/introduction.rst diff --git a/doc/conf.py b/doc/conf.py index fc1342280..c9522f9ca 100644 --- a/doc/conf.py +++ b/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 --------------------------------------------------- diff --git a/doc/user_guide/features/ignore_ruff_findings.rst b/doc/user_guide/features/ignore_ruff_findings.rst index c111c996d..e106d06b4 100644 --- a/doc/user_guide/features/ignore_ruff_findings.rst +++ b/doc/user_guide/features/ignore_ruff_findings.rst @@ -12,4 +12,7 @@ You can ignore this finding by appending a comment to the code line: from exasol.toolbox.nox.tasks import * # noqa: F403 -See `Ruff documentation `_ +See also + +* `Ruff documentation `_ +* :ref:`Ignoring Ruff formatting` diff --git a/doc/user_guide/getting_started.rst b/doc/user_guide/getting_started.rst index 528556ee8..d7dd2d5a2 100644 --- a/doc/user_guide/getting_started.rst +++ b/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 `_ installed: + To establish a new project with toolbox support, you need to have + `Cookiecutter `_ 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 ++++++++++++++++++++++++++++++++++ diff --git a/doc/user_guide/introduction.rst b/doc/user_guide/introduction.rst deleted file mode 100644 index ece671d3b..000000000 --- a/doc/user_guide/introduction.rst +++ /dev/null @@ -1,34 +0,0 @@ -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/migrating.rst b/doc/user_guide/migrating.rst index f0d26192e..d4bdcc26f 100644 --- a/doc/user_guide/migrating.rst +++ b/doc/user_guide/migrating.rst @@ -1,3 +1,5 @@ +.. _migrating_legacy_projects: + Migrating Legacy Projects ========================= diff --git a/doc/user_guide/troubleshooting.rst b/doc/user_guide/troubleshooting.rst index d8707b3a7..7fb6aa909 100644 --- a/doc/user_guide/troubleshooting.rst +++ b/doc/user_guide/troubleshooting.rst @@ -3,9 +3,14 @@ Troubleshooting =============== +This page helps you in case some of the a :ref:`tools employed by the PTB +` do not exactly what you want or might report errors you want to +ignore for sound reasons. Some of the proposed mitigations are specific to +the related tool. + .. toctree:: :maxdepth: 1 Formatting issues - features/metrics/ignore_findings - features/ignore_ruff_findings + Ruff findings + Sonar findings diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index 9fcda4964..83ee69ba5 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -5,8 +5,8 @@ .. toctree:: :maxdepth: 2 + :hidden: - introduction dependencies getting_started configuration @@ -14,3 +14,36 @@ troubleshooting customization migrating + +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 + From 000270ffb599b486fd85a854ee0a1d47845686b3 Mon Sep 17 00:00:00 2001 From: ckunki Date: Wed, 18 Feb 2026 11:26:29 +0100 Subject: [PATCH 3/6] fixed redirects --- doc/user_guide/user_guide.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index 83ee69ba5..2f12f5a5d 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -36,14 +36,13 @@ 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 +.. _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 -.. _Cookiecutter: https://cookiecutter.readthedocs.io -.. _Mypy: https://mypy.readthedocs.io -.. _Coverage: https://coverage.readthedocs.io -.. _Bandit: https://bandit.readthedocs.io +.. _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 - From a80bedc6ab9886c7901e3aeb9fce40e559d8333a Mon Sep 17 00:00:00 2001 From: ckunki Date: Wed, 18 Feb 2026 12:28:09 +0100 Subject: [PATCH 4/6] Restructured global troubleshooting page Moved formatting troubleshooting too global directory --- .../features/formatting_code/index.rst | 2 +- .../formatting_code/troubleshooting.rst | 70 ++----------------- doc/user_guide/troubleshooting.rst | 16 ----- ...eck_errors_due_to_configuration_issues.rst | 11 +++ .../format_check_reports_unmodified_files.rst | 27 +++++++ .../troubleshooting/formatting_disable.rst | 34 +++++++++ .../ignore_ruff_findings.rst | 2 +- doc/user_guide/troubleshooting/index.rst | 20 ++++++ doc/user_guide/user_guide.rst | 2 +- 9 files changed, 100 insertions(+), 84 deletions(-) delete mode 100644 doc/user_guide/troubleshooting.rst create mode 100644 doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst create mode 100644 doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst create mode 100644 doc/user_guide/troubleshooting/formatting_disable.rst rename doc/user_guide/{features => troubleshooting}/ignore_ruff_findings.rst (89%) create mode 100644 doc/user_guide/troubleshooting/index.rst diff --git a/doc/user_guide/features/formatting_code/index.rst b/doc/user_guide/features/formatting_code/index.rst index 8c2840c83..bced4e2bc 100644 --- a/doc/user_guide/features/formatting_code/index.rst +++ b/doc/user_guide/features/formatting_code/index.rst @@ -4,7 +4,7 @@ Formatting code =============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 configuration troubleshooting diff --git a/doc/user_guide/features/formatting_code/troubleshooting.rst b/doc/user_guide/features/formatting_code/troubleshooting.rst index 71eb64b4b..001ec0001 100644 --- a/doc/user_guide/features/formatting_code/troubleshooting.rst +++ b/doc/user_guide/features/formatting_code/troubleshooting.rst @@ -3,69 +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 | -| | | -| | # fmt: on | -+-----------------------+--------------------------------+-----------------------+ -| formatting from isort | .. code-block:: python | .. code-block:: python| -| | | | -| | # isort:skip| # isort:skip_file | -+-----------------------+--------------------------------+-----------------------+ -| formatting from ruff | .. code-block:: python | .. code-block:: python| -| (example with F401) | | | -| | # 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 ------------------------------------------------------------------------------------- - -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 `. -#. 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 diff --git a/doc/user_guide/troubleshooting.rst b/doc/user_guide/troubleshooting.rst deleted file mode 100644 index 7fb6aa909..000000000 --- a/doc/user_guide/troubleshooting.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _ptb_troubleshooting: - -Troubleshooting -=============== - -This page helps you in case some of the a :ref:`tools employed by the PTB -` do not exactly what you want or might report errors you want to -ignore for sound reasons. Some of the proposed mitigations are specific to -the related tool. - -.. toctree:: - :maxdepth: 1 - - Formatting issues - Ruff findings - Sonar findings diff --git a/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst b/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst new file mode 100644 index 000000000..68236a2b6 --- /dev/null +++ b/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst @@ -0,0 +1,11 @@ +Format Check Errors Due to Configuration Issues +=============================================== + +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`. diff --git a/doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst b/doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst new file mode 100644 index 000000000..a74668b0e --- /dev/null +++ b/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`` reports 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 `. +#. 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. diff --git a/doc/user_guide/troubleshooting/formatting_disable.rst b/doc/user_guide/troubleshooting/formatting_disable.rst new file mode 100644 index 000000000..7f011fada --- /dev/null +++ b/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 | +| | | +| | # fmt: on | ++-----------------------+--------------------------------+-----------------------+ +| formatting from isort | .. code-block:: python | .. code-block:: python| +| | | | +| | # isort:skip| # isort:skip_file | ++-----------------------+--------------------------------+-----------------------+ +| formatting from ruff | .. code-block:: python | .. code-block:: python| +| (example with F401) | | | +| | # noqa: F401| # ruff: noqa F401 | ++-----------------------+--------------------------------+-----------------------+ + +See also :ref:`ignore_ruff_findings`. diff --git a/doc/user_guide/features/ignore_ruff_findings.rst b/doc/user_guide/troubleshooting/ignore_ruff_findings.rst similarity index 89% rename from doc/user_guide/features/ignore_ruff_findings.rst rename to doc/user_guide/troubleshooting/ignore_ruff_findings.rst index e106d06b4..6ca9d020d 100644 --- a/doc/user_guide/features/ignore_ruff_findings.rst +++ b/doc/user_guide/troubleshooting/ignore_ruff_findings.rst @@ -15,4 +15,4 @@ You can ignore this finding by appending a comment to the code line: See also * `Ruff documentation `_ -* :ref:`Ignoring Ruff formatting` +* :ref:`prevent_auto_format` diff --git a/doc/user_guide/troubleshooting/index.rst b/doc/user_guide/troubleshooting/index.rst new file mode 100644 index 000000000..e82db4c2f --- /dev/null +++ b/doc/user_guide/troubleshooting/index.rst @@ -0,0 +1,20 @@ +.. _ptb_troubleshooting: + +Troubleshooting +=============== + +This page helps you in case some of the a :ref:`tools employed by the PTB +` do not exactly 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) + Sonar findings <../features/metrics/ignore_findings> diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index 2f12f5a5d..603722044 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -11,7 +11,7 @@ getting_started configuration features/index - troubleshooting + troubleshooting/index customization migrating From 582e2ba02e1c0c9498393ec4574b917378b1aeeb Mon Sep 17 00:00:00 2001 From: Christoph Kuhnke Date: Wed, 18 Feb 2026 15:00:49 +0100 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Steffen Pankratz --- .../format_check_errors_due_to_configuration_issues.rst | 4 ++-- .../troubleshooting/format_check_reports_unmodified_files.rst | 4 ++-- doc/user_guide/troubleshooting/index.rst | 4 ++-- doc/user_guide/user_guide.rst | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst b/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst index 68236a2b6..30ff7b550 100644 --- a/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst +++ b/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst @@ -1,11 +1,11 @@ Format Check Errors Due to Configuration Issues =============================================== -If when you execute: +When you execute: #. Run ``format:fix`` #. Run ``format:check`` -you receive an error from ``format:check`` (i.e. ``isort`` or ``black``), it it +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`. diff --git a/doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst b/doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst index a74668b0e..6847a32e9 100644 --- a/doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst +++ b/doc/user_guide/troubleshooting/format_check_reports_unmodified_files.rst @@ -3,7 +3,7 @@ Format Check Reports Unmodified Files ===================================== -Sometimes ``checks.yml`` or ``format:check`` reports formatting issues in +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 @@ -21,7 +21,7 @@ If you encounter this scenario, please: #. Reset your ``poetry.lock`` to align with what's in the project's **default branch**. #. More selectively update your ``poetry.lock`` with `poetry update `. #. 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 + 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. diff --git a/doc/user_guide/troubleshooting/index.rst b/doc/user_guide/troubleshooting/index.rst index e82db4c2f..17dcd94af 100644 --- a/doc/user_guide/troubleshooting/index.rst +++ b/doc/user_guide/troubleshooting/index.rst @@ -3,8 +3,8 @@ Troubleshooting =============== -This page helps you in case some of the a :ref:`tools employed by the PTB -` do not exactly what you want or might report errors you want to +This page helps you in case some of the :ref:`tools employed by the PTB +` 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 diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index 603722044..6106e019c 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -17,14 +17,14 @@ 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. +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 +* `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 From 725622bb3db5a0b8d522665e4fbd4c0592c1606b Mon Sep 17 00:00:00 2001 From: ckunki Date: Wed, 18 Feb 2026 15:02:12 +0100 Subject: [PATCH 6/6] updated review suggestions --- .../format_check_errors_due_to_configuration_issues.rst | 4 ++-- doc/user_guide/troubleshooting/index.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst b/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst index 30ff7b550..5e5e7eb8d 100644 --- a/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst +++ b/doc/user_guide/troubleshooting/format_check_errors_due_to_configuration_issues.rst @@ -6,6 +6,6 @@ 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 +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`. diff --git a/doc/user_guide/troubleshooting/index.rst b/doc/user_guide/troubleshooting/index.rst index 17dcd94af..585fc995a 100644 --- a/doc/user_guide/troubleshooting/index.rst +++ b/doc/user_guide/troubleshooting/index.rst @@ -4,8 +4,8 @@ Troubleshooting =============== This page helps you in case some of the :ref:`tools employed by the PTB -` do not exactly do what you want or might report errors you want to -ignore for sound reasons. +` 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.