From 8980561298b15ed3428c4c0fb74d147d0e2bad53 Mon Sep 17 00:00:00 2001
From: Rain <rain@sunshowers.io>
Date: Mon, 30 Oct 2023 17:05:12 -0700
Subject: [PATCH] [site] expand test coverage instructions

Fixes #1080.
---
 site/src/book/test-coverage.md | 38 ++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/site/src/book/test-coverage.md b/site/src/book/test-coverage.md
index b81444a9508..363f049a567 100644
--- a/site/src/book/test-coverage.md
+++ b/site/src/book/test-coverage.md
@@ -26,9 +26,43 @@ Install Rust with the `llvm-tools-preview` component, nextest, and llvm-cov in G
   run: cargo llvm-cov nextest
 ```
 
-[See this in practice with nextest's own CI.](https://github.com/nextest-rs/nextest/blob/main/.github/workflows/coverage.yml)
+### Collecting coverage data from doctests
 
-> TODO: provide instructions for other report forms like HTML, and for reporting to an external code coverage service.
+Nextest doesn't currently support doctests, so coverage data from nextest must be [merged](https://github.com/taiki-e/cargo-llvm-cov?tab=readme-ov-file#merge-coverages-generated-under-different-test-conditions) with doctest data.
+
+Here's an example GitHub Actions configuration:
+
+```yaml
+# Nightly Rust is required for cargo llvm-cov --doc.
+- uses: dtolnay/rust-toolchain@nightly
+  with:
+    components: llvm-tools-preview
+- uses: taiki-e/install-action@cargo-llvm-cov
+- uses: taiki-e/install-action@nextest
+
+- name: Collect coverage data (including doctests)
+  run: |
+    cargo llvm-cov --no-report nextest
+    cargo llvm-cov --no-report --doc
+    cargo llvm-cov report --doctests --lcov --output-path lcov.info
+```
+
+### Reporting to an external coverage service
+
+External services like [Codecov.io](https://about.codecov.io/) can be used to collect and display coverage data. Codecov is free for open source projects, and supports `lcov.info` files.
+
+After generating an `lcov.info` file, upload it to Codecov with:
+
+```yaml
+- name: Upload coverage data to codecov
+  uses: codecov/codecov-action@v3
+  with:
+    files: lcov.info
+```
+
+### Example
+
+Nextest itself uses the above mechanisms to collect coverage for its project. The config is located in [`.github/workflows/coverage.yml`](https://github.com/nextest-rs/nextest/blob/main/.github/workflows/coverage.yml).
 
 ## Integrating nextest into coverage tools