SCANPY-156 Expand documentation for the pysonar-scanner by guillaume-dequenne · Pull Request #186 · SonarSource/sonar-scanner-python

guillaume-dequenne · 2025-04-02T09:19:55Z

Seppli11

Overall, this looks really good.
I really like the approach with the CLI_ARGS.md since it guarantees that it is always up to date.

I've left a few comments. Some personal preferences and remarks, others corrections.

Seppli11 · 2025-04-02T12:48:53Z


- - SonarQube v9.9 or higher
+ - SonarQube v10.6 or above
 - Python 3.8 or above


We require python 3.9

Suggested change

- Python 3.8 or above

- Python 3.9 or above

Seppli11 · 2025-04-02T12:53:27Z

-When a `pyproject.toml` file is available, it is possible to set the `-read-project-config` flag
-to allow the scanner to deduce analysis properties from the project configuration.
+```
+pysonar --sonar-projectBaseDir "path/to/projectBaseDir"


I think you meant -Dsonar.projectBaseDir here, since --sonar-projectBaseDir doesn't exist.

Suggested change

pysonar --sonar-projectBaseDir "path/to/projectBaseDir"

pysonar -Dsonar.projectBaseDir="path/to/projectBaseDir"

Seppli11 · 2025-04-02T13:12:54Z

    - poetry run licenseheaders -t license_header.tmpl -o "SonarSource SA" -y 2011-2024 -n "Sonar Scanner Python" -E .py -d tests/
    - git diff --name-only --exit-code ./src ./tests

+documentation_task:


awesome 💪

Seppli11 · 2025-04-02T13:15:11Z

 Analysis properties can be provided as CLI arguments to the `pysonar` command.
-They follow the same convention as when running the SonarScanner CLI directly 
-(see [documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/#running-from-zip-file)).
+They can be provided in a similar way as when running the SonarScanner CLI directly 


Personally, I would have formulated this the other way around. E.g. use --token and --sonar-region by default. If the argument is not available, -D... works for everything, but we don't verify and blindly forward it

I intentionally framed it that way so that the first information is the one that will definitely work, then only later we provide a way to make it less verbose for specific properties.
I feel that reduces the risk of mistakes if someone only skims the documentation. Does it make sense?

Yeah, I think so.

Seppli11 · 2025-04-02T13:17:41Z

+
+    # Group arguments by category
+    categories = {
+        "Authentication": ["token", "sonar_host_url", "sonar_region"],


we probably should also add sonar_organization here (depending if #188 is merged first)

thomas-serre-sonarsource · 2025-04-02T13:56:21Z

The result looks good!

thomas-serre-sonarsource · 2025-04-02T13:57:10Z

+1. Through CLI arguments to the `pysonar` command
+2. Environment variables for individual properties (e.g. `SONAR_TOKEN`, `SONAR_VERBOSE`, `SONAR_HOST_URL`, ...)
+3. Generic environment variable `SONAR_SCANNER_JSON_PARAMS` 
+4. Under the `[tool.sonar]` key of the `pyproject.toml` file
+5. In a dedicated `sonar-project.properties` file
+6. Through common properties extracted from the `pyproject.toml`


thomas-serre-sonarsource · 2025-04-02T14:00:11Z


-You can use all the argument allowed by __SonarScanner__. 
-For more information on __SonarScanner__ please refer to the [SonarScanner documentation](https://docs.sonarsource.com/sonarqube/9.9/analyzing-source-code/scanners/sonarscanner/)
+You can use all the arguments allowed by __SonarScanner__. 


It could be worth it to mention that we support also Python specific properties like sonar.python.version

I'm tempted to think it's implied, since CLI_ARGS.md mentions them explicitly.
We could keep a list of Python specific properties documented separately though, but I feel it might be overkill at this point?

thomas-serre-sonarsource · 2025-04-02T14:07:44Z

+            "flake8_report_paths",
+            "ruff_report_paths",
+        ],
+        "Other": [],  # Will contain everything else


I'd like to see a Python specific section with :
--sonar-cpd-python-minimum-lines
--sonar-cpd-python-minimum-tokens
--sonar-python-skip-unchanged
--toml-path
--sonar-python-skip-unchanged
--sonar-python-xunit-skip-details
--sonar-python-version

As discussed, it probably make sense to have amore granular split of the "Other" category, but I'm not sure doing it through Python-exclusive section makes sense for the end user (they probably care more about what the property achieve rather than the fact it's specific to the Python analyzer). As a baby step, let's keep it like this and revisit later.

sonarqube-next · 2025-04-02T14:10:41Z

Quality Gate passed for 'Python Scanner'

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

thomas-serre-sonarsource

I like the idea !
I left a few subjective comments :)

Seppli11

LGTM! Thanks for the quick changes

guillaume-dequenne force-pushed the SCANPY-156 branch 4 times, most recently from da8768f to 2015180 Compare April 2, 2025 09:47

guillaume-dequenne changed the title ~~SCANPY-156~~ SCANPY-156 Expand documentation for the pysonar-scanner Apr 2, 2025

guillaume-dequenne force-pushed the SCANPY-156 branch 9 times, most recently from b148d21 to bd673ea Compare April 2, 2025 12:37

guillaume-dequenne requested review from Seppli11 and thomas-serre-sonarsource April 2, 2025 12:42

guillaume-dequenne marked this pull request as ready for review April 2, 2025 13:10

guillaume-dequenne force-pushed the SCANPY-156 branch from b4dae8f to a7df32a Compare April 2, 2025 13:11

Seppli11 requested changes Apr 2, 2025

View reviewed changes

thomas-serre-sonarsource reviewed Apr 2, 2025

View reviewed changes

Comment thread CLI_ARGS.md

Copy link
Copy Markdown

Contributor

thomas-serre-sonarsource Apr 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The result looks good!

thomas-serre-sonarsource reviewed Apr 2, 2025

View reviewed changes

guillaume-dequenne added 4 commits April 2, 2025 16:08

SCANPY-156 Expand documentation for the pysonar-scanner

3fd8bbd

Automatically generate documentation for CLI args

8642097

Add CI task to validate documentation

c8d9d54

Fix after review

335ac21

guillaume-dequenne force-pushed the SCANPY-156 branch from a7df32a to 335ac21 Compare April 2, 2025 14:09

thomas-serre-sonarsource reviewed Apr 2, 2025

View reviewed changes

guillaume-dequenne requested a review from Seppli11 April 2, 2025 14:22

Seppli11 approved these changes Apr 2, 2025

View reviewed changes

Seppli11 merged commit 49e7c9f into master Apr 2, 2025
18 checks passed

Seppli11 deleted the SCANPY-156 branch April 2, 2025 14:25

	pysonar --sonar-projectBaseDir "path/to/projectBaseDir"
	pysonar -Dsonar.projectBaseDir="path/to/projectBaseDir"

Conversation

guillaume-dequenne commented Apr 2, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Seppli11 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqube-next bot commented Apr 2, 2025

Quality Gate passed for 'Python Scanner'

Uh oh!

thomas-serre-sonarsource left a comment

Choose a reason for hiding this comment

Uh oh!

Seppli11 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

guillaume-dequenne commented Apr 2, 2025 •

edited by atlassian bot

Loading