docs: Add lcov / codecov options for nox coverage and update docs (#3825

)

* docs: Clarify use of llmv-cov plugin

* Mention first-run

* Update Contributing.md

* Add options

* fix

.gitignore

@@ -22,5 +22,6 @@ pip-wheel-metadata
 valgrind-python.supp
 *.pyd
 lcov.info
+coverage.json
 netlify_build/
 .nox/

Contributing.md

@@ -177,9 +177,14 @@ Second, there is a Python-based benchmark contained in the `pytests` subdirector
 
 You can view what code is and isn't covered by PyO3's tests. We aim to have 100% coverage - please check coverage and add tests if you notice a lack of coverage!
 
-- First, generate a `lcov.info` file with
+- First, ensure the llmv-cov cargo plugin is installed. You may need to run the plugin through cargo once before using it with `nox`.
 ```shell
-nox -s coverage
+cargo install cargo-llvm-cov
+cargo llvm-cov
+```
+- Then, generate an `lcov.info` file with
+```shell
+nox -s coverage -- lcov
 ```
 You can install an IDE plugin to view the coverage. For example, if you use VSCode:
 - Add the [coverage-gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) plugin.

noxfile.py

@@ -61,6 +61,14 @@ def coverage(session: nox.Session) -> None:
     session.env.update(_get_coverage_env())
     _run_cargo(session, "llvm-cov", "clean", "--workspace")
     test(session)
+
+    cov_format = "codecov"
+    output_file = "coverage.json"
+
+    if "lcov" in session.posargs:
+        cov_format = "lcov"
+        output_file = "lcov.info"
+
     _run_cargo(
         session,
         "llvm-cov",
@@ -70,9 +78,9 @@ def coverage(session: nox.Session) -> None:
         "--package=pyo3-macros",
         "--package=pyo3-ffi",
         "report",
-        "--codecov",
+        f"--{cov_format}",
         "--output-path",
-        "coverage.json",
+        output_file,
     )