From af80b4c933d2a786833b1eca0053ace8f0d2569a Mon Sep 17 00:00:00 2001 From: ckunki Date: Fri, 9 Jan 2026 13:47:21 +0100 Subject: [PATCH 1/5] #648: Moved sonar setup instructions in the User guide --- doc/changes/unreleased.md | 4 + .../features/metrics/collecting_metrics.rst | 7 +- .../features/metrics/project_report.rst | 4 +- doc/user_guide/features/metrics/sonar.rst | 116 +----------------- doc/user_guide/features/sonar_setup.rst | 114 +++++++++++++++++ doc/user_guide/user_guide.rst | 1 + 6 files changed, 126 insertions(+), 120 deletions(-) create mode 100644 doc/user_guide/features/sonar_setup.rst diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 79e701b84..f39cbc15e 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -1 +1,5 @@ # Unreleased + +## Documentation + +* #648: Moved sonar setup instructions in the User guide diff --git a/doc/user_guide/features/metrics/collecting_metrics.rst b/doc/user_guide/features/metrics/collecting_metrics.rst index e69f51374..6367655c8 100644 --- a/doc/user_guide/features/metrics/collecting_metrics.rst +++ b/doc/user_guide/features/metrics/collecting_metrics.rst @@ -1,6 +1,10 @@ Collecting metrics ================== +The PTB allows you to collect various metrics on the quality of your project +regarding Coverage, Security, and Static Code Analysis. There are two options +for reporting the metrics: + .. toctree:: :maxdepth: 2 @@ -12,9 +16,6 @@ Collecting metrics Generated metrics +++++++++++++++++ -The PTB allows you to collect various metrics on the quality of your project -regarding Coverage, Security, and Static Code Analysis. - For each metric, there is a dedicated nox session, generating one or multiple files and based on a selected external Python tool. diff --git a/doc/user_guide/features/metrics/project_report.rst b/doc/user_guide/features/metrics/project_report.rst index 92f3aa036..7e79d5878 100644 --- a/doc/user_guide/features/metrics/project_report.rst +++ b/doc/user_guide/features/metrics/project_report.rst @@ -1,7 +1,7 @@ .. _project_report: -``project:report`` -================== +Nox task ``project:report`` +=========================== After collecting the metrics described in by :ref:`generated_metrics`, you can use the nox session ``project:report`` to create a report using one of the following formats: diff --git a/doc/user_guide/features/metrics/sonar.rst b/doc/user_guide/features/metrics/sonar.rst index 2db9c69ed..5d5c197b3 100644 --- a/doc/user_guide/features/metrics/sonar.rst +++ b/doc/user_guide/features/metrics/sonar.rst @@ -12,120 +12,6 @@ SonarQube analysis fails. The PTB includes instructions to set up a GitHub bot to display the results of the Sonar analysis in your pull requests as a stylized comment and workflow result. -Section :ref:`configuration` gives instructions for public and private repositories. - -.. _configuration: - -Configuration -+++++++++++++ - -.. _configure_sonar_public_project: - -**Public** GitHub repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In GitHub -""""""""" -A GitHub Admin will need to: - -#. Inherit organization secret 'SONAR_TOKEN' -#. Activate the `SonarQubeCloud App `__ -#. **Post-merge**: update the branch protections to include SonarQube analysis. - - * This should only be done when tests exist for the project, & that the project is - at a state in which enforced code coverage would not be a burden. If you do - not enact branch protections, it is recommended to create an issue to do so later. - -In Sonar -"""""""" -#. Create a project on `SonarCloud `__ - - * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` - * To alter the project further, you will need the help of a SonarQube Admin. - -In the code -""""""""""" -#. In the ``noxconfig.py``, the relative path to the project's source code is defined with ``Config.sonar_code_path``. -#. Add the following to the project's file ``pyproject.toml`` - .. code-block:: toml - - [tool.sonar] - projectKey = "" - host.url = "https://sonarcloud.io" - organization = "exasol" - exclusions = "/version.py,//*" - -.. note:: - For more information, see the :ref:`General remarks ` section. - - -.. _configure_sonar_private_project: - -**Private** GitHub repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: - As of 2025-07-29, these instructions have not been used. Thus, they should be - scrutinized and refined when they are used to configure a private repository. - -In GitHub -""""""""" -A GitHub Admin will need to: - -#. Add the individual 'PRIVATE_SONAR_TOKEN' to the 'Organization secrets' -#. Activate the `exasonarqubeprchecks App `__ -#. **Post-merge**: update the branch protections to include SonarQube analysis. - - * This should only be done when tests exist for the project, & that the project is - at a state in which enforced code coverage would not be a burden. If you do - not enact branch protections, it is recommended to create an issue to do so later. - -In Sonar -"""""""" -An IT Admin will need to: - -#. Create a project on https://sonar.exasol.com - - * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` - - -In the code -""""""""""" -#. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source`` - .. code-block:: python - - source: Path = Path("exasol/") - -#. Add the following to the project's file ``pyproject.toml`` - .. code-block:: toml - - [tool.sonar] - projectKey = "com.exasol:" - host.url = "https://sonar.exasol.com" - organization = "exasol" - exclusions = "/version.py,//*" - -.. note:: - For more information, see the :ref:`General remarks ` section. +Section :ref:`sonarqube_configuration` gives instructions for public and private repositories. .. _Exasol Way: https://sonarcloud.io/organizations/exasol/quality_gates/show/AXxvLH-3BdtLlpiYmZhh -.. _Sonar Matching Patterns: https://docs.sonarsource.com/sonarqube-server/project-administration/adjusting-analysis/setting-analysis-scope/defining-matching-patterns - -.. _configuration_general_remarks: - -General remarks -^^^^^^^^^^^^^^^^^^^ -For additional configuration information, see `Sonar's analysis parameters `__ page. - -``exclusions`` -"""""""""""""" -With the value of ``exclusions``, you can exclude files and directories of your -project from Sonar's analysis: - -* You can use wildcards, e.g. ``/dir/*.py`` or ``/**/*.py`` -* Multiple exclusions can be comma-separated (as shown above). -* For excluding arbitrary directories and files below a specific directory, please use two asterisks, e.g. ``root/abc/**``. - -See the `Sonar Matching Patterns`_ for more details. - -By default, the nox session ``sonar:check`` only analyses the source code, -as specified by the ``PROJECT_CONFIG.sonar_code_path``, so directories outside of this -are already excluded from being analyzed. diff --git a/doc/user_guide/features/sonar_setup.rst b/doc/user_guide/features/sonar_setup.rst new file mode 100644 index 000000000..5a00df6b1 --- /dev/null +++ b/doc/user_guide/features/sonar_setup.rst @@ -0,0 +1,114 @@ +.. _sonarqube_configuration: + +SonarQube Configuration ++++++++++++++++++++++++ + +.. _configure_sonar_public_project: + +**Public** GitHub repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In GitHub +""""""""" +A GitHub Admin will need to: + +#. Inherit organization secret 'SONAR_TOKEN' +#. Activate the `SonarQubeCloud App `__ +#. **Post-merge**: update the branch protections to include SonarQube analysis. + + * This should only be done when tests exist for the project, & that the project is + at a state in which enforced code coverage would not be a burden. If you do + not enact branch protections, it is recommended to create an issue to do so later. + +In Sonar +"""""""" +#. Create a project on `SonarCloud `__ + + * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` + * To alter the project further, you will need the help of a SonarQube Admin. + +In the code +""""""""""" +#. In the ``noxconfig.py``, the relative path to the project's source code is defined with ``Config.sonar_code_path``. +#. Add the following to the project's file ``pyproject.toml`` + .. code-block:: toml + + [tool.sonar] + projectKey = "" + host.url = "https://sonarcloud.io" + organization = "exasol" + exclusions = "/version.py,//*" + +.. note:: + For more information, see the :ref:`General remarks ` section. + + +.. _configure_sonar_private_project: + +**Private** GitHub repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. note:: + As of 2025-07-29, these instructions have not been used. Thus, they should be + scrutinized and refined when they are used to configure a private repository. + +In GitHub +""""""""" +A GitHub Admin will need to: + +#. Add the individual 'PRIVATE_SONAR_TOKEN' to the 'Organization secrets' +#. Activate the `exasonarqubeprchecks App `__ +#. **Post-merge**: update the branch protections to include SonarQube analysis. + + * This should only be done when tests exist for the project, & that the project is + at a state in which enforced code coverage would not be a burden. If you do + not enact branch protections, it is recommended to create an issue to do so later. + +In Sonar +"""""""" +An IT Admin will need to: + +#. Create a project on https://sonar.exasol.com + + * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` + + +In the code +""""""""""" +#. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source`` + .. code-block:: python + + source: Path = Path("exasol/") + +#. Add the following to the project's file ``pyproject.toml`` + .. code-block:: toml + + [tool.sonar] + projectKey = "com.exasol:" + host.url = "https://sonar.exasol.com" + organization = "exasol" + exclusions = "/version.py,//*" + +.. note:: + For more information, see the :ref:`General remarks ` section. + +.. _Sonar Matching Patterns: https://docs.sonarsource.com/sonarqube-server/project-administration/adjusting-analysis/setting-analysis-scope/defining-matching-patterns + +.. _configuration_general_remarks: + +General remarks +^^^^^^^^^^^^^^^^^^^ +For additional configuration information, see `Sonar's analysis parameters `__ page. + +``exclusions`` +"""""""""""""" +With the value of ``exclusions``, you can exclude files and directories of your +project from Sonar's analysis: + +* You can use wildcards, e.g. ``/dir/*.py`` or ``/**/*.py`` +* Multiple exclusions can be comma-separated (as shown above). +* For excluding arbitrary directories and files below a specific directory, please use two asterisks, e.g. ``root/abc/**``. + +See the `Sonar Matching Patterns`_ for more details. + +By default, the nox session ``sonar:check`` only analyses the source code, +as specified by the ``PROJECT_CONFIG.sonar_code_path``, so directories outside of this +are already excluded from being analyzed. diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index ad7576938..9752883f3 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -8,6 +8,7 @@ dependencies getting_started + features/sonar_setup features/index workflows customization From fc5c34d52eeceb04b1a676c6e728dd1449ca1716 Mon Sep 17 00:00:00 2001 From: Christoph Kuhnke Date: Fri, 9 Jan 2026 13:53:37 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Ariel Schulz <43442541+ArBridgeman@users.noreply.github.com> --- doc/user_guide/features/metrics/project_report.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/features/metrics/project_report.rst b/doc/user_guide/features/metrics/project_report.rst index 7e79d5878..fa5777e79 100644 --- a/doc/user_guide/features/metrics/project_report.rst +++ b/doc/user_guide/features/metrics/project_report.rst @@ -1,6 +1,6 @@ .. _project_report: -Nox task ``project:report`` +Nox session ``project:report`` =========================== After collecting the metrics described in by :ref:`generated_metrics`, you can use the nox session ``project:report`` to create a report using one of the following formats: From a2ffff4e05769ca653a8eb188af7bd9b0a5c44a2 Mon Sep 17 00:00:00 2001 From: ckunki Date: Fri, 9 Jan 2026 13:54:36 +0100 Subject: [PATCH 3/5] Fixed headline underlining --- doc/user_guide/features/metrics/project_report.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/features/metrics/project_report.rst b/doc/user_guide/features/metrics/project_report.rst index fa5777e79..78cbd248f 100644 --- a/doc/user_guide/features/metrics/project_report.rst +++ b/doc/user_guide/features/metrics/project_report.rst @@ -1,7 +1,8 @@ .. _project_report: Nox session ``project:report`` -=========================== +============================== + After collecting the metrics described in by :ref:`generated_metrics`, you can use the nox session ``project:report`` to create a report using one of the following formats: From 8edf7d39fc7fb44f6abb1687767944763333f4e2 Mon Sep 17 00:00:00 2001 From: ckunki Date: Fri, 9 Jan 2026 14:37:13 +0100 Subject: [PATCH 4/5] Added central page for configuration options --- doc/user_guide/configuration.rst | 13 ++ .../formatting_code/configuration.rst | 54 ++++++++ .../features/formatting_code/index.rst | 55 +------- doc/user_guide/features/index.rst | 16 +-- doc/user_guide/features/metrics/sonar.rst | 118 +++++++++++++++++- doc/user_guide/features/sonar_setup.rst | 114 ----------------- doc/user_guide/user_guide.rst | 2 +- 7 files changed, 193 insertions(+), 179 deletions(-) create mode 100644 doc/user_guide/configuration.rst create mode 100644 doc/user_guide/features/formatting_code/configuration.rst delete mode 100644 doc/user_guide/features/sonar_setup.rst diff --git a/doc/user_guide/configuration.rst b/doc/user_guide/configuration.rst new file mode 100644 index 000000000..0967c43f0 --- /dev/null +++ b/doc/user_guide/configuration.rst @@ -0,0 +1,13 @@ +.. _ptb_configuration: + +Configuration +============= + +Many components of the PTB can be configured. Adjustment might be required +especially when starting a new project. + +.. toctree:: + :maxdepth: 1 + + features/metrics/sonar + Formatting diff --git a/doc/user_guide/features/formatting_code/configuration.rst b/doc/user_guide/features/formatting_code/configuration.rst new file mode 100644 index 000000000..7a7135265 --- /dev/null +++ b/doc/user_guide/features/formatting_code/configuration.rst @@ -0,0 +1,54 @@ +.. _formatting_configuration: + +Configuring Formatting +++++++++++++++++++++++ + +black +^^^^^ + +Your ``black`` configuration should look similar to this: + +.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml + :language: toml + :start-at: [tool.black] + :end-before: [tool.isort] + +For further configuration options, see +`black configuration `__. + +isort +^^^^^ + +Ensure ``isort`` is configured with compatibility for ``black``: + +.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml + :language: toml + :start-at: [tool.isort] + :end-before: [tool.pylint.master] + +For further configuration options, see +`isort options `__. + + +pyupgrade +^^^^^^^^^ + +No initial configuration of ``pyupgrade`` is required. By default, this is +configured to be derived from the minimum Python version that your project supports +and is defined in the :meth:`exasol.toolbox.config.BaseConfig.pyupgrade_argument`. + +For further configuration options, see the +`pyupgrade documentation `__. + +ruff +^^^^ + +Ensure ``ruff`` is configured like so: + +.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml + :language: toml + :start-at: [tool.ruff.lint] + :end-before: [tool.mypy.overrides] + +For further configuration options, see +`ruff options `__. diff --git a/doc/user_guide/features/formatting_code/index.rst b/doc/user_guide/features/formatting_code/index.rst index a720a43a6..8c2840c83 100644 --- a/doc/user_guide/features/formatting_code/index.rst +++ b/doc/user_guide/features/formatting_code/index.rst @@ -6,6 +6,7 @@ Formatting code .. toctree:: :maxdepth: 2 + configuration troubleshooting The PTB automatically formats code and ensures via a step in the ``checks.yml`` GitHub @@ -51,57 +52,3 @@ deterministic manner. | | | need to be re-formatted | +--------------------+------------------+------------------------------------+ -.. _formatting_configuration: - -Configuration -+++++++++++++ - -black -^^^^^ - -Your ``black`` configuration should look similar to this: - -.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml - :language: toml - :start-at: [tool.black] - :end-before: [tool.isort] - -For further configuration options, see -`black configuration `__. - -isort -^^^^^ - -Ensure ``isort`` is configured with compatibility for ``black``: - -.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml - :language: toml - :start-at: [tool.isort] - :end-before: [tool.pylint.master] - -For further configuration options, see -`isort options `__. - - -pyupgrade -^^^^^^^^^ - -No initial configuration of ``pyupgrade`` is required. By default, this is -configured to be derived from the minimum Python version that your project supports -and is defined in the :meth:`exasol.toolbox.config.BaseConfig.pyupgrade_argument`. - -For further configuration options, see the -`pyupgrade documentation `__. - -ruff -^^^^ - -Ensure ``ruff`` is configured like so: - -.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml - :language: toml - :start-at: [tool.ruff.lint] - :end-before: [tool.mypy.overrides] - -For further configuration options, see -`ruff options `__. diff --git a/doc/user_guide/features/index.rst b/doc/user_guide/features/index.rst index 97be87e1d..6a57544fd 100644 --- a/doc/user_guide/features/index.rst +++ b/doc/user_guide/features/index.rst @@ -4,14 +4,14 @@ Features ======== .. toctree:: - :maxdepth: 2 - - metrics/collecting_metrics - creating_a_release - documentation/index - git_hooks/index - formatting_code/index - managing_dependencies + :maxdepth: 2 + + metrics/collecting_metrics + creating_a_release + documentation/index + git_hooks/index + formatting_code/index + managing_dependencies Uniform Project Layout ---------------------- diff --git a/doc/user_guide/features/metrics/sonar.rst b/doc/user_guide/features/metrics/sonar.rst index 5d5c197b3..91db1cfe5 100644 --- a/doc/user_guide/features/metrics/sonar.rst +++ b/doc/user_guide/features/metrics/sonar.rst @@ -1,6 +1,6 @@ .. _sonarqube_analysis: -SonarQube analysis +SonarQube Analysis ================== The PTB supports using `SonarQube Cloud `__ @@ -12,6 +12,120 @@ SonarQube analysis fails. The PTB includes instructions to set up a GitHub bot to display the results of the Sonar analysis in your pull requests as a stylized comment and workflow result. -Section :ref:`sonarqube_configuration` gives instructions for public and private repositories. +Section :ref:`sonar_configuration` gives instructions for public and private repositories. + +.. _sonar_configuration: + +Configuration ++++++++++++++ + +.. _configure_sonar_public_project: + +**Public** GitHub repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In GitHub +""""""""" +A GitHub Admin will need to: + +#. Inherit organization secret 'SONAR_TOKEN' +#. Activate the `SonarQubeCloud App `__ +#. **Post-merge**: update the branch protections to include SonarQube analysis. + + * This should only be done when tests exist for the project, & that the project is + at a state in which enforced code coverage would not be a burden. If you do + not enact branch protections, it is recommended to create an issue to do so later. + +In Sonar +"""""""" +#. Create a project on `SonarCloud `__ + + * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` + * To alter the project further, you will need the help of a SonarQube Admin. + +In the code +""""""""""" +#. In the ``noxconfig.py``, the relative path to the project's source code is defined with ``Config.sonar_code_path``. +#. Add the following to the project's file ``pyproject.toml`` + .. code-block:: toml + + [tool.sonar] + projectKey = "" + host.url = "https://sonarcloud.io" + organization = "exasol" + exclusions = "/version.py,//*" + +.. note:: + For more information, see the :ref:`General remarks ` section. + + +.. _configure_sonar_private_project: + +**Private** GitHub repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. note:: + As of 2025-07-29, these instructions have not been used. Thus, they should be + scrutinized and refined when they are used to configure a private repository. + +In GitHub +""""""""" +A GitHub Admin will need to: + +#. Add the individual 'PRIVATE_SONAR_TOKEN' to the 'Organization secrets' +#. Activate the `exasonarqubeprchecks App `__ +#. **Post-merge**: update the branch protections to include SonarQube analysis. + + * This should only be done when tests exist for the project, & that the project is + at a state in which enforced code coverage would not be a burden. If you do + not enact branch protections, it is recommended to create an issue to do so later. + +In Sonar +"""""""" +An IT Admin will need to: + +#. Create a project on https://sonar.exasol.com + + * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` + + +In the code +""""""""""" +#. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source`` + .. code-block:: python + + source: Path = Path("exasol/") + +#. Add the following to the project's file ``pyproject.toml`` + .. code-block:: toml + + [tool.sonar] + projectKey = "com.exasol:" + host.url = "https://sonar.exasol.com" + organization = "exasol" + exclusions = "/version.py,//*" + +.. note:: + For more information, see the :ref:`General remarks ` section. .. _Exasol Way: https://sonarcloud.io/organizations/exasol/quality_gates/show/AXxvLH-3BdtLlpiYmZhh +.. _Sonar Matching Patterns: https://docs.sonarsource.com/sonarqube-server/project-administration/adjusting-analysis/setting-analysis-scope/defining-matching-patterns + +.. _configuration_general_remarks: + +General remarks +^^^^^^^^^^^^^^^^^^^ +For additional configuration information, see `Sonar's analysis parameters `__ page. + +``exclusions`` +"""""""""""""" +With the value of ``exclusions``, you can exclude files and directories of your +project from Sonar's analysis: + +* You can use wildcards, e.g. ``/dir/*.py`` or ``/**/*.py`` +* Multiple exclusions can be comma-separated (as shown above). +* For excluding arbitrary directories and files below a specific directory, please use two asterisks, e.g. ``root/abc/**``. + +See the `Sonar Matching Patterns`_ for more details. + +By default, the nox session ``sonar:check`` only analyses the source code, +as specified by the ``PROJECT_CONFIG.sonar_code_path``, so directories outside of this +are already excluded from being analyzed. diff --git a/doc/user_guide/features/sonar_setup.rst b/doc/user_guide/features/sonar_setup.rst deleted file mode 100644 index 5a00df6b1..000000000 --- a/doc/user_guide/features/sonar_setup.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. _sonarqube_configuration: - -SonarQube Configuration -+++++++++++++++++++++++ - -.. _configure_sonar_public_project: - -**Public** GitHub repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In GitHub -""""""""" -A GitHub Admin will need to: - -#. Inherit organization secret 'SONAR_TOKEN' -#. Activate the `SonarQubeCloud App `__ -#. **Post-merge**: update the branch protections to include SonarQube analysis. - - * This should only be done when tests exist for the project, & that the project is - at a state in which enforced code coverage would not be a burden. If you do - not enact branch protections, it is recommended to create an issue to do so later. - -In Sonar -"""""""" -#. Create a project on `SonarCloud `__ - - * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` - * To alter the project further, you will need the help of a SonarQube Admin. - -In the code -""""""""""" -#. In the ``noxconfig.py``, the relative path to the project's source code is defined with ``Config.sonar_code_path``. -#. Add the following to the project's file ``pyproject.toml`` - .. code-block:: toml - - [tool.sonar] - projectKey = "" - host.url = "https://sonarcloud.io" - organization = "exasol" - exclusions = "/version.py,//*" - -.. note:: - For more information, see the :ref:`General remarks ` section. - - -.. _configure_sonar_private_project: - -**Private** GitHub repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: - As of 2025-07-29, these instructions have not been used. Thus, they should be - scrutinized and refined when they are used to configure a private repository. - -In GitHub -""""""""" -A GitHub Admin will need to: - -#. Add the individual 'PRIVATE_SONAR_TOKEN' to the 'Organization secrets' -#. Activate the `exasonarqubeprchecks App `__ -#. **Post-merge**: update the branch protections to include SonarQube analysis. - - * This should only be done when tests exist for the project, & that the project is - at a state in which enforced code coverage would not be a burden. If you do - not enact branch protections, it is recommended to create an issue to do so later. - -In Sonar -"""""""" -An IT Admin will need to: - -#. Create a project on https://sonar.exasol.com - - * Project key should follow this pattern, e.g. ``com.exasol:python-toolbox`` - - -In the code -""""""""""" -#. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source`` - .. code-block:: python - - source: Path = Path("exasol/") - -#. Add the following to the project's file ``pyproject.toml`` - .. code-block:: toml - - [tool.sonar] - projectKey = "com.exasol:" - host.url = "https://sonar.exasol.com" - organization = "exasol" - exclusions = "/version.py,//*" - -.. note:: - For more information, see the :ref:`General remarks ` section. - -.. _Sonar Matching Patterns: https://docs.sonarsource.com/sonarqube-server/project-administration/adjusting-analysis/setting-analysis-scope/defining-matching-patterns - -.. _configuration_general_remarks: - -General remarks -^^^^^^^^^^^^^^^^^^^ -For additional configuration information, see `Sonar's analysis parameters `__ page. - -``exclusions`` -"""""""""""""" -With the value of ``exclusions``, you can exclude files and directories of your -project from Sonar's analysis: - -* You can use wildcards, e.g. ``/dir/*.py`` or ``/**/*.py`` -* Multiple exclusions can be comma-separated (as shown above). -* For excluding arbitrary directories and files below a specific directory, please use two asterisks, e.g. ``root/abc/**``. - -See the `Sonar Matching Patterns`_ for more details. - -By default, the nox session ``sonar:check`` only analyses the source code, -as specified by the ``PROJECT_CONFIG.sonar_code_path``, so directories outside of this -are already excluded from being analyzed. diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index 9752883f3..1e2957b3e 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -8,7 +8,7 @@ dependencies getting_started - features/sonar_setup + configuration features/index workflows customization From 2bda3d02b6cb5ace4110c8380301bb57cc1c6c9d Mon Sep 17 00:00:00 2001 From: ckunki Date: Fri, 9 Jan 2026 14:46:04 +0100 Subject: [PATCH 5/5] Made local toc hidden in collecting_metrics --- .../features/metrics/collecting_metrics.rst | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/doc/user_guide/features/metrics/collecting_metrics.rst b/doc/user_guide/features/metrics/collecting_metrics.rst index 6367655c8..521595851 100644 --- a/doc/user_guide/features/metrics/collecting_metrics.rst +++ b/doc/user_guide/features/metrics/collecting_metrics.rst @@ -1,20 +1,20 @@ -Collecting metrics +Collecting Metrics ================== The PTB allows you to collect various metrics on the quality of your project -regarding Coverage, Security, and Static Code Analysis. There are two options -for reporting the metrics: +regarding Coverage, Security, and Static Code Analysis. .. toctree:: - :maxdepth: 2 + :maxdepth: 2 + :hidden: - project_report - sonar + project_report + sonar .. _generated_metrics: -Generated metrics -+++++++++++++++++ +Generating Metrics +++++++++++++++++++ For each metric, there is a dedicated nox session, generating one or multiple files and based on a selected external Python tool. @@ -40,13 +40,13 @@ The GitHub workflows of your project can: * Define multiple test sessions, e.g. for distinguishing fast vs. slow or expensive tests. -Reporting metrics +Reporting Metrics +++++++++++++++++ Currently, the PTB offers two methods to aggregate the :ref:`generated_metrics` into a report: -#. the nox session ``project:report`` +#. Nox session ``project:report`` This is an Exasol-specific summarization tool. For more information, see :ref:`project_report`. #. SonarQube analysis @@ -54,10 +54,11 @@ into a report: `Sonar `__. For further details, see :ref:`sonarqube_analysis` -Both of these reporting options require that the generated files from the :ref:`generated_metrics` -are existing and in the expected formats. As there are metrics for different Python -versions, the PTB uses only the metrics associated with the Python version named first -in the attribute ``python_versions`` of class ``Config`` to the reporting metrics tools. +Both of these reporting options require that the generated files from the +generated metrics are existing and in the expected formats. As there are +metrics for different Python versions, the PTB uses only the metrics +associated with the Python version named first in the attribute +``python_versions`` of class ``Config`` to the reporting metrics tools. To perform this validation, there are two nox sessions. Due to the direct dependence on the nox session ``project:report`` and SonarQube Analysis on the