#648: Moved sonar setup instructions in the User guide

doc/changes/unreleased.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+## Documentation
+
+* #648: Moved sonar setup instructions in the User guide
+
 ## Features
 
 * #649: Restricted noxconfig usage throughout exasol.toolbox to only exasol.toolbox.nox.*

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 <features/formatting_code/configuration>

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 <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-format>`__.
+
+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 <https://pycqa.github.io/isort/docs/configuration/options.html>`__.
+
+
+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 <https://pypi.org/project/pyupgrade/>`__.
+
+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 <https://docs.astral.sh/ruff/configuration>`__.

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 <https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-format>`__.
-
-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 <https://pycqa.github.io/isort/docs/configuration/options.html>`__.
-
-
-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 <https://pypi.org/project/pyupgrade/>`__.
-
-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 <https://docs.astral.sh/ruff/configuration>`__.

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
 ----------------------

doc/user_guide/features/metrics/collecting_metrics.rst

@@ -1,19 +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.
+
 .. toctree::
-    :maxdepth: 2
+   :maxdepth: 2
+   :hidden:
 
-    project_report
-    sonar
+   project_report
+   sonar
 
 .. _generated_metrics:
 
-Generated metrics
-+++++++++++++++++
-
-The PTB allows you to collect various metrics on the quality of your project
-regarding Coverage, Security, and Static Code Analysis.
+Generating Metrics
+++++++++++++++++++
 
 For each metric, there is a dedicated nox session, generating one or multiple
 files and based on a selected external Python tool.
@@ -39,24 +40,25 @@ 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
     This summarization tool feeds into a feature-rich UI provided by
     `Sonar <https://docs.sonarsource.com/sonarqube-server>`__. 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

doc/user_guide/features/metrics/project_report.rst

@@ -1,7 +1,8 @@
 .. _project_report:
 
-``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:
 

doc/user_guide/features/metrics/sonar.rst

@@ -1,6 +1,6 @@
 .. _sonarqube_analysis:
 
-SonarQube analysis
+SonarQube Analysis
 ==================
 
 The PTB supports using `SonarQube Cloud <https://docs.sonarsource.com/sonarqube-server>`__
@@ -12,9 +12,9 @@ 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.
+Section :ref:`sonar_configuration` gives instructions for public and private repositories.
 
-.. _configuration:
+.. _sonar_configuration:
 
 Configuration
 +++++++++++++

doc/user_guide/user_guide.rst

@@ -8,6 +8,7 @@
 
     dependencies
     getting_started
+    configuration
     features/index
     workflows
     customization