Switch to paragraph form for instructions so clearer who is actor & where

Author: ArBridgeman

doc/user_guide/features/metrics/sonar.rst

@@ -25,28 +25,41 @@ Configuration
 
 **Public** GitHub repository
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-1. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source``
+In GitHub
+"""""""""
+A GitHub Admin will need to:
+
+#. Inherit organization secret 'SONAR_TOKEN'
+#. Activate the `SonarQubeCloud App <https://github.com/apps/sonarqubecloud>`__
+#. **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. For new projects,
+    we recommend creating an issue to add the SonarQube analysis to the branch protections
+    at a later point. In such scenarios, SonarQube analysis will still report its analysis
+    results to the PR, but it will not prevent the PR from being merged.
+
+In Sonar
+""""""""
+#. Create a project on `SonarCloud <https://sonarcloud.io>`__
+
+  * 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
+"""""""""""
+#. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source``
     .. code-block:: python
 
-        source: Path = Path("exasol/<project-source-folder>")
-2. Add the 'SONAR_TOKEN' to the 'Organization secrets' in GitHub
-3. Activate the `SonarQubeCloud App <https://github.com/apps/sonarqubecloud>`__
-4. Create a project on `SonarCloud <https://sonarcloud.io>`__
-5. Add the following information to the project's file ``pyproject.toml``
+        source: Path = Path("exasol/<source-directory>")
+#. Add the following to the project's file ``pyproject.toml``
     .. code-block:: toml
 
         [tool.sonar]
-        projectKey = "com.exasol:<project-key>"
+        projectKey = "<sonar-project-key>"
         hostUrl = "https://sonarcloud.io"
         organization = "exasol"
         exclusions = "<source-directory>/version.py,<source_directory>/<directory-to-ignore>/*"
-6. 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. For new projects,
-    we recommend creating an issue to add the SonarQube analysis to the branch protections
-    at a later point. In such scenarios, SonarQube analysis will still report its analysis
-    results to the PR, but it will not prevent the PR from being merged.
 
 .. _configure_sonar_private_project:
 
@@ -56,27 +69,43 @@ Configuration
     As of 2025-07-29, we do not currently have a private project configured. Thus,
     these instructions should be scrutinized and refined upon the configuration of one.
 
-1. Specify in the ``noxconfig.py`` the relative path to the project's source code in ``Config.source``
+In GitHub
+"""""""""
+A GitHub Admin will need to:
+
+#. Add the individual 'PRIVATE_SONAR_TOKEN' to the 'Organization secrets'
+#. Activate the `exasonarqubeprchecks App <https://github.com/apps/exasonarqubeprchecks>`__
+#. **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. For new projects,
+    we recommend creating an issue to add the SonarQube analysis to the branch protections
+    at a later point. In such scenarios, SonarQube analysis will still report its analysis
+    results to the PR, but it will not prevent the PR from being merged.
+
+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/<project-source-folder>")
-2. Add the individual 'PRIVATE_SONAR_TOKEN' to the 'Organization secrets' in GitHub
-3. Activate the `exasonarqubeprchecks App <https://github.com/apps/exasonarqubeprchecks>`__
-4. Create a project on https://sonar.exasol.com
-5. Add the following information to the project's file `pyproject.toml`
+        source: Path = Path("exasol/<source-directory>")
+
+#. Add the following to the project's file ``pyproject.toml``
     .. code-block:: toml
 
         [tool.sonar]
         projectKey = "com.exasol:<project-key>"
         hostUrl = "https://sonar.exasol.com"
         organization = "exasol"
         exclusions = "<source-directory>/version.py,<source_directory>/<directory-to-ignore>/*"
-6. Post-merge, update the branch protections to include SonarQube analysis from exasonarqubeprchecks
-
-  * 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. For new projects,
-    we recommend creating an issue to add the SonarQube analysis to the branch protections
-    at a later point. In such scenarios, SonarQube analysis will still report its analysis
-    results to the PR, but it will not prevent the PR from being merged.
 
 .. _Exasol Way: https://sonarcloud.io/organizations/exasol/quality_gates/show/AXxvLH-3BdtLlpiYmZhh