From 0f92b670b2a474acc2a8faf44b1f1926ddfb741a Mon Sep 17 00:00:00 2001
From: Alexander Hill <me@alxhill.com>
Date: Fri, 23 Feb 2024 01:49:44 -0500
Subject: [PATCH] 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      |  1 +
 Contributing.md |  9 +++++++--
 noxfile.py      | 12 ++++++++++--
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 4240d326f71..d27dfa6f9a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,5 +22,6 @@ pip-wheel-metadata
 valgrind-python.supp
 *.pyd
 lcov.info
+coverage.json
 netlify_build/
 .nox/
diff --git a/Contributing.md b/Contributing.md
index dad543856cc..f87fffc0906 100644
--- a/Contributing.md
+++ b/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.
diff --git a/noxfile.py b/noxfile.py
index 00288273aec..add737e5f15 100644
--- a/noxfile.py
+++ b/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,
     )