diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 77106267c..a2e204d6c 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/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/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 97e26207f..001ec0001 100644 --- a/doc/user_guide/features/formatting_code/troubleshooting.rst +++ b/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 | -| | | -| | # 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 | -+-----------------------+--------------------------------+-----------------------+ - - -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/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/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 deleted file mode 100644 index ba1232fca..000000000 --- a/doc/user_guide/troubleshooting.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _ptb_troubleshooting: - -Troubleshooting -=============== - -.. toctree:: - :maxdepth: 1 - - features/metrics/ignore_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/troubleshooting/ignore_ruff_findings.rst b/doc/user_guide/troubleshooting/ignore_ruff_findings.rst new file mode 100644 index 000000000..6ca9d020d --- /dev/null +++ b/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 `_ +* :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 00c8009fa..603722044 100644 --- a/doc/user_guide/user_guide.rst +++ b/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 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/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