Documentation/589 fix sonar documentation (#594)

* Corrected configuration for Sonar documentation for host.url

* Add new line after header at the top of the versionsed changelog

* Add reference to Sonar's analysis parameter page

* Add more information about exclusions

* Add and correct information on pyupgrade usage

* Reduce duplicate information by creating a General remarks section

Author: ArBridgeman

doc/changes/unreleased.md

@@ -1 +1,11 @@
 # Unreleased
+
+## Documentation
+
+* #589: Corrected configuration for Sonar documentation for host.url
+* #535: Added more information about Sonar's usage of ``exclusions``
+* #596: Corrected and added more information regarding ``pyupgrade``
+
+## Refactoring
+
+* #596: Added newline after header in versioned changelog

doc/user_guide/features/formatting_code/index.rst

@@ -44,6 +44,7 @@ deterministic manner.
 
 Configuration
 +++++++++++++
+
 black
 ^^^^^
 
@@ -59,6 +60,7 @@ For further configuration options, see
 
 isort
 ^^^^^
+
 Ensure ``isort`` is configured with compatibility for ``black``:
 
 .. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml
@@ -72,9 +74,10 @@ For further configuration options, see
 
 pyupgrade
 ^^^^^^^^^
-No initial configuration of ``pyupgrade`` is required.
 
-For individual configuration, see the
-`pyupgrade CLI options <https://pypi.org/project/pyupgrade/>`__. These can
-be passed to the :ref:`formatting_sessions` via the ``pyupgrade_args``
-attribute of the :class:`noxconfig.Config`.
+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/>`__.

doc/user_guide/features/metrics/sonar.rst

@@ -53,10 +53,14 @@ In the code
 
         [tool.sonar]
         projectKey = "<sonar-project-key>"
-        hostUrl = "https://sonarcloud.io"
+        host.url = "https://sonarcloud.io"
         organization = "exasol"
         exclusions = "<source-directory>/version.py,<source_directory>/<directory-to-ignore>/*"
 
+.. note::
+    For more information, see the :ref:`General remarks <configuration_general_remarks>` section.
+
+
 .. _configure_sonar_private_project:
 
 **Private** GitHub repository
@@ -98,8 +102,33 @@ In the code
 
         [tool.sonar]
         projectKey = "com.exasol:<project-key>"
-        hostUrl = "https://sonar.exasol.com"
+        host.url = "https://sonar.exasol.com"
         organization = "exasol"
         exclusions = "<source-directory>/version.py,<source_directory>/<directory-to-ignore>/*"
 
+.. note::
+    For more information, see the :ref:`General remarks <configuration_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/setting-analysis-scope/defining-matching-patterns
+
+.. _configuration_general_remarks:
+
+General remarks
+^^^^^^^^^^^^^^^^^^^
+For additional configuration information, see `Sonar's analysis parameters <https://docs.sonarsource.com/sonarqube-server/2025.1/analyzing-source-code/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. ``<root>/dir/*.py`` or ``<root>/**/*.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.source``, so directories outside of this
+are already excluded from being analyzed.

exasol/toolbox/util/release/changelog.py

@@ -50,7 +50,7 @@ def _create_versioned_changelog(self, unreleased_content: str) -> None:
         if dependency_changes := self._describe_dependency_changes():
             dependency_content = f"## Dependency Updates\n{dependency_changes}"
 
-        template = cleandoc(f"{header}\n{unreleased_content}\n{dependency_content}")
+        template = cleandoc(f"{header}\n\n{unreleased_content}\n{dependency_content}")
         self.versioned_changelog_md.write_text(template + "\n")
 
     def _extract_unreleased_notes(self) -> str:

project-template/{{cookiecutter.repo_name}}/pyproject.toml

@@ -65,6 +65,6 @@ ignore_errors = true
 
 [tool.sonar]
 projectKey = "com.exasol:{{cookiecutter.repo_name}}"
-hostUrl = "https://sonarcloud.io"
+host.url = "https://sonarcloud.io"
 organization = "exasol"
 exclusions = "exasol/{{cookiecutter.package_name}}/version.py"

pyproject.toml

@@ -120,6 +120,6 @@ poetry-plugin-export = ">=1.8"
 
 [tool.sonar]
 projectKey = "com.exasol:python-toolbox"
-hostUrl = "https://sonarcloud.io"
+host.url = "https://sonarcloud.io"
 organization = "exasol"
 exclusions = "exasol/toolbox/version.py"

test/unit/util/release/changelog_test.py

@@ -181,6 +181,7 @@ def test_update_changelogs_for_release(
             saved_text
             == cleandoc(
                 f"""# 1.0.0 - {datetime.today().strftime('%Y-%m-%d')}
+
             ## Added
             * Added Awesome feature
 
@@ -218,6 +219,7 @@ def test_update_changelogs_for_release_with_no_dependencies(
             saved_text
             == cleandoc(
                 f"""# 1.0.0 - {datetime.today().strftime('%Y-%m-%d')}
+
             ## Added
             * Added Awesome feature