From b5e9e385dcbb7991b32a3e4d405f46795e6937a1 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 25 Aug 2026 00:22:31 +0000
Subject: [PATCH] docs: describe Literate scripts as a lightweight doc-testing
 mechanism

Addresses feedback in #1221 by explicitly documenting that Literate's
--eval execution of embedded F# code, combined with (*** include-output ***)
and (*** include-value ***), functions as a low-effort doc-test workflow:
code samples are executed for real and failures surface at build time.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/literate.fsx | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/literate.fsx b/docs/literate.fsx
index a22907a23..a40b57163 100644
--- a/docs/literate.fsx
+++ b/docs/literate.fsx
@@ -282,3 +282,21 @@ All of the three methods discussed in the previous two sections take a number of
 parameters that can be used to tweak how the formatting works
 
 *)
+
+(**
+## Using Literate scripts as doc tests
+
+Because Literate scripts execute embedded F# code via F# Interactive when the `eval` option
+(or `fsdocs build --eval` / `fsdocs watch --eval`) is enabled, they double as a lightweight
+form of "doc testing": the code samples in your documentation are run for real, and any
+exceptions raised during evaluation cause the build to fail (or, with the `(*** include-output ***)`
+directive, the *actual* output of the snippet is captured and included verbatim in the
+generated page). This means documentation examples can't silently drift out of sync with
+the API they describe — if a sample stops compiling or throws, you'll find out the next
+time the docs are built.
+
+This is not a full doc-test framework (there's no built-in support for asserting expected
+output against actual output), but combined with `(*** include-output ***)` and
+`(*** include-value ***)` it gives a useful low-effort way to keep documentation examples
+honest.
+*)