Document usethis show sonarqube more thoroughly (#1562)

Copilot · nathanjmcdougall · web-flow · commit 7affbc87ab84 · 2026-03-27T11:35:42.000+13:00
* Initial plan * Initial plan for documenting usethis show sonarqube Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/6eb5954c-e7c1-4b82-a6a7-1c4e88071a68 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> * docs: document usethis show sonarqube behavior more thoroughly Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/6eb5954c-e7c1-4b82-a6a7-1c4e88071a68 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Co-authored-by: Nathan McDougall <nathan.j.mcdougall@gmail.com>
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
@@ -456,7 +456,24 @@ Currently supported subcommands:
 
 - `usethis show backend` to show the inferred project manager backend, e.g. 'uv' or 'none'. This is the default backend used, i.e. when `--backend=auto` is specified.
 - `usethis show name` to show the name of the project.
-- `usethis show sonarqube` to show appropriate contents of a `sonar-projects.properties` file for SonarQube analysis.
+- `usethis show sonarqube` to show appropriate contents of a `sonar-project.properties` file for SonarQube analysis.
+
+### `usethis show sonarqube`
+
+Show the contents of a `sonar-project.properties` file for SonarQube analysis.
+
+If a `sonar-project.properties` file already exists in the project root, its contents are returned as-is. In this case, the `--project-key` option and `tool.usethis.sonarqube.project-key` in `pyproject.toml` are both ignored.
+
+If no `sonar-project.properties` file exists, the contents are constructed from `pyproject.toml` configuration. In this case, a project key is required:
+
+- If `--project-key` is provided, it is used.
+- Otherwise, `tool.usethis.sonarqube.project-key` from `pyproject.toml` is used.
+
+Additional configuration in `pyproject.toml`:
+
+- `tool.usethis.sonarqube.verbose` (bool, default `false`) — sets `sonar.verbose`.
+- `tool.usethis.sonarqube.exclusions` (list of strings, default `[]`) — sets `sonar.exclusions`.
+- `tool.coverage.xml.output` (string, required) — sets `sonar.python.coverage.reportPaths`.
 
 ## `usethis browse pypi <package>`
 
